local-falcon-tool

name	local-falcon-tool
description	When the user wants to run a geogrid scan, check existing scan reports, track ranking trends over time, monitor GBP changes via Falcon Guard, or analyze reviews. Also use when the user says "run a scan," "check my rankings," "Local Falcon," "how am I ranking," "ranking heatmap," or "scan this keyword." This is the execution tool — for interpreting results, also load geogrid-analysis.
metadata	{"version":"1.0.0","author":"Garrett Smith"}

Local Falcon Tool

Note: LocalSEOData (localseodata-tool) now has a geogrid_scan endpoint for one-time ranking scans. Use LocalSEOData for quick audits and one-off scans. Local Falcon remains essential for trend reports, recurring campaigns, Falcon Guard monitoring, and AI platform scans (GAIO/ChatGPT/Gemini/Grok).

You have direct access to Local Falcon via MCP. This skill tells you WHEN to use each operation and WHAT to do with the results.

When to Use Local Falcon vs Other Tools

You Need	Use Local Falcon	Use Instead
Rankings across a geographic area	✅ Geogrid scans	—
Rankings at one specific point	✅ Can do it but overkill	SerpAPI for quick spot-check
Competitor rankings in an area	✅ Competitor reports auto-generated	—
Ranking trends over time	✅ Trend reports	—
GBP monitoring for changes	✅ Falcon Guard	—
Review analysis with sentiment	✅ Reviews Analysis	—
Keyword search volume	❌	Semrush, Ahrefs, DataForSEO
Backlink data	❌	Ahrefs, Semrush
Website traffic data	❌	Google Analytics
Technical site audit	❌	Screaming Frog

Before Running Any Scan

Always check existing reports first. Scans cost credits. Don't duplicate work.

Step 1: listAllLocalFalconLocations → Find the place ID
Step 2: listLocalFalconScanReports (filter by placeId + keyword) → Check if a recent scan exists
Step 3: Only run a NEW scan if no recent report exists or the user explicitly wants fresh data

Core Workflows

Run a New Ranking Scan

When: User wants to know how a business ranks for a keyword across a geographic area.

1. Find the business: listAllLocalFalconLocations — search by name or address
   • If not found: searchForLocalFalconBusinessLocation → saveLocalFalconBusinessLocationToAccount
2. Confirm scan parameters with user:
   • Keyword (what customers search)
   • Grid size (see grid table below)
   • Radius (see radius table below)
   • Platform: google, apple, gaio, chatgpt, gemini, grok, aimode
   • AI analysis: yes/no (Google only, recommended)
3. Run: runLocalFalconScan — returns immediately with "submitted"
4. Poll: listLocalFalconScanReports (filter by placeId) — check every 30 seconds
5. Retrieve: getLocalFalconReport with fieldmask for analysis
6. Interpret: Use geogrid-analysis skill to diagnose results

Recommended fieldmask for analysis: report_key,date,place_id,keyword,location,arp,atrp,solv,found_in,total_competitors,grid_size,radius,measurement,ai_analysis,image,heatmap

Check Existing Reports

When: User asks about current/recent rankings, or you need baseline data.

1. listLocalFalconScanReports with filters (placeId, keyword, date range)
2. Use fieldmask: report_key,date,keyword,location.name,arp,atrp,solv,grid_size,platform
3. If multiple reports exist for same keyword: getLocalFalconTrendReport for the trend view

Track Ranking Trends

When: User wants to see if rankings are improving or declining.

1. listLocalFalconTrendReports (filter by placeId and keyword)
2. getLocalFalconTrendReport — returns historical ARP, ATRP, SoLV per scan date
3. Compare metrics across dates and correlate with optimization actions

Key insight: Trend reports only exist when 2+ scans have identical settings (same placeId, keyword, grid size, radius, coordinates). If settings differ between scans, no trend report is generated.

Run a Campaign (Recurring Scans)

When: User wants automated regular scanning.

1. listLocalFalconCampaignReports — check existing campaigns first
2. createLocalFalconCampaign — set up keyword(s), location(s), frequency, grid size
3. Campaign runs automatically on schedule
4. getLocalFalconCampaignReport — retrieve aggregated results

Campaign vs individual scans: Campaigns consolidate data in one report. Individual scans generate separate trend/location/keyword reports. Use campaigns for ongoing monitoring, individual scans for one-off analysis.

Competitive Analysis

When: User wants to know who's beating them.

1. Every scan auto-generates a competitor report
2. getLocalFalconCompetitorReports — list available reports
3. getLocalFalconCompetitorReport — top competitors with ARP, ATRP, SoLV, reviews, ratings
4. Use fieldmask: date,keyword,grid_size,radius,businesses.*.name,businesses.*.place_id,businesses.*.arp,businesses.*.atrp,businesses.*.solv,businesses.*.reviews,businesses.*.rating

Monitor GBP for Changes (Falcon Guard)

When: User wants to protect their GBP from unauthorized edits.

1. listLocalFalconGuardReports — see what's currently monitored
2. addLocationsToFalconGuard — add locations to monitoring
3. getLocalFalconGuardReport — view change history and metrics (calls, clicks, directions for OAuth-connected locations)

Review Analysis

When: User wants AI-powered review insights.

1. listLocalFalconReviewsAnalysisReports — check existing analyses
2. getLocalFalconReviewsAnalysisReport — full sentiment analysis, topics, competitor comparison

Grid Size Selection

Business Type	Grid Size	Radius	Rationale
Coffee shop, salon, restaurant	5×5 or 7×7	1-3 mi	Customers walk/drive short distances
Dentist, chiropractor, single-location medical	7×7 or 9×9	3-7 mi	City-wide draw
HVAC, plumber, electrician	9×9 or 11×11	7-15 mi	Wide service area
Hospital system, franchise chain	13×13 or 15×15	10-20 mi	Regional coverage
Rural business	7×7 or 9×9	15-30 mi	Large but sparse area

Rule of thumb: Grid size should cover the realistic service area. Too small = misleading good results. Too big = misleading bad results.

Credit Awareness

• Always check credits before running scans: viewLocalFalconAccountInformation
• Larger grids cost more credits
• Campaigns multiply: locations × keywords × frequency
• AI analysis adds cost per scan
• Never re-run a scan without checking if results already exist

What to Do Next

What You Got	Next Action	Skill
Scan results with ARP/ATRP/SoLV	Interpret the data and diagnose issues	geogrid-analysis
Competitor report data	Analyze what competitors do differently	local-competitor-analysis
Trend showing decline	Diagnose cause using decision trees	geogrid-analysis diagnostic trees
GBP changes detected via Guard	Review and revert unauthorized edits	gbp-optimization
Review analysis results	Build review strategy from insights	review-management

Default next step: Never return raw scan numbers to the user. Always interpret through geogrid-analysis first.