Urs

Each dimension scores 0–100 with confidence 0–1. The composite is a weighted average. Tiers: 80–100 = Highly responsive, 60–79 = Moderately responsive, 40–59 = Mixed signals, 20–39 = Likely slow, 0–19 = Structurally unresponsive.

When to Use Each Tool

• urs_import_eia — When the user needs more utilities than the seed provides, or wants to populate the DB. Import from EIA-861 CSV via file_path (local) or url. Covers ~3,300 US utilities. Download from eia.gov/electricity/data/eia861/.
• urs_lookup — First step when the user mentions a utility by name, state, or ID. Resolves to EIA Utility ID. If ambiguous, present candidates and ask the user to choose.
• urs_score — When the user wants to score, evaluate, or compare utilities. Call with utility_id from lookup. Include mw_requirement, target_isd, use_case if the user stated them.
• urs_ingest — When the user provides a document (IRP, tariff filing, earnings transcript) to add to the knowledge base. Requires file path, source type, utility ID.
• urs_fetch_edgar — When the user wants to pull 10-K/10-Q filings from SEC EDGAR for an investor-owned utility. Fetches from SEC's free API, optionally ingests for scoring. Only works for utilities with a CIK mapping (see data/edgar-cik-map.ts). APS (803), Duke (6452), Dominion (13998) are mapped.
• urs_fetch_pudl — When the user wants FERC Form 1 data for track_record. Uses PUDL (Catalyst Cooperative). Requires ferc_id on utility. Downloads ferc1_dbf.sqlite from Zenodo on first run (~271MB). Pass pudl_sqlite_path for local file.
• urs_fetch_eia — When the user wants EIA retail sales/customers data for track_record. Requires EIA_API_KEY (free at eia.gov/opendata).
• urs_fetch_legiscan — When the user wants state energy/datacenter legislation for regulatory_environment. Requires LEGISCAN_API_KEY (free, 30k/month). Pass state or utility_id.
• urs_fetch_hifld — When the user wants to enrich utilities with HIFLD territory metadata (names, addresses, types). No API key. Filter by state or utility_name.
• urs_history — When the user asks for score history or trends over time.
• urs_sources — When the user asks what data backs a score, or which sources are stale.
• urs_fetch_legiscan — When the user wants to search state legislature bills related to energy/datacenters. Searches LegiScan API (free tier: 30k queries/month). Requires LEGISCAN_API_KEY from legiscan.com. Feeds regulatory_environment dimension. Use state to filter by state, query for custom search, or leave blank for default datacenter/energy keywords. Set utility_id + ingest: true to extract and store signals.
• urs_fetch_puc_dockets — When the user wants to pull state PUC/PSC docket filings. Supports automated scrapers for AZ (ACC eDocket), NC (NCUC), TX (PUCT Interchange). For other states, use url param to manually fetch + ingest a docket document, or download the file and use urs_ingest directly. Use list_systems: true to see all known PUC systems. Affects all scoring dimensions.
• urs_arcgis_sync — When the user wants to push scores to a map/ArcGIS.
• urs_arcgis_pull — When the user wants to pull utility data or scores from ArcGIS. Use persist: true to save pulled utilities into the local DB for lookups and scoring.

Workflow Examples

"I need Arizona utilities" / "Populate the DB" / "Pull utilities into the database"

1. urs_import_eia with url (if a known EIA-861 CSV URL exists) or file_path to a downloaded CSV
2. Or urs_arcgis_pull with state: "AZ" and persist: true if ArcGIS already has the data
3. Then urs_lookup and urs_score as needed

"Get SEC filings for APS" / "Ingest 10-K for Arizona Public Service"

1. urs_lookup("Arizona Public Service") → utility_id 803
2. urs_fetch_edgar(utility_id="803") — fetches 10-K and 10-Q, ingests for scoring
3. urs_score(utility_id="803") to see improved score with new data

"Get FERC Form 1 data for Duke" / "Improve track record for Dominion"

1. urs_lookup to get utility_id (must have ferc_id in DB)
2. urs_fetch_pudl(utility_id="6452") — fetches PUDL FERC Form 1, writes track_record signals
3. urs_score to see improved track_record dimension

"Get EIA retail data for APS"

1. urs_fetch_eia(utility_id="803") — requires EIA_API_KEY
2. urs_score(utility_id="803")

"What energy legislation exists in Arizona?"

1. urs_fetch_legiscan(state="AZ") or urs_fetch_legiscan(utility_id="803")
2. Bills cached; optionally ingested for regulatory_environment

"Enrich utilities with HIFLD territory data"

1. urs_fetch_hifld(state="AZ") — fetches and upserts utility metadata

"How responsive is Duke Energy Carolinas?"

1. urs_lookup("Duke Energy Carolinas") → get utility_id 6452
2. urs_score(utility_id="6452")
3. Present score and rationale conversationally

"Compare Duke and Dominion in Virginia"

1. urs_lookup("Duke Energy") and urs_lookup("Dominion Energy Virginia") — resolve to specific utilities
2. urs_score for each
3. Present side-by-side comparison, highlight differences

"I need 200MW online by mid-2027 in North Carolina"

1. urs_lookup to find NC utilities (Duke Energy Carolinas, Duke Energy Progress, etc.)
2. Offer to score the relevant ones
3. When scoring, pass mw_requirement=200, target_isd="2027-06-01"
4. If user cares about interconnection speed, suggest weight_overrides: { interconnection_speed: 1.5 }

"What energy bills are being proposed in Arizona?" / "Search for datacenter legislation"

1. urs_fetch_legiscan(state="AZ") — searches with default datacenter/energy keywords
2. Or urs_fetch_legiscan(state="AZ", query="datacenter AND rate") for specific terms
3. Review bills, optionally ingest relevant ones with utility_id for scoring

"Get Arizona PUC dockets about datacenters" / "Pull rate case filings from NC"

1. urs_fetch_puc_dockets(state="AZ", search_query="datacenter") — uses ACC eDocket scraper
2. Or urs_fetch_puc_dockets(state="AZ", docket_number="E-00000A-25-0069") for specific docket
3. For unsupported states: urs_fetch_puc_dockets(state="VA", url="https://...", utility_id="13998")
4. Or download file + urs_ingest(file_path="...", source_type="rate_case", utility_id="13998")
5. Use urs_fetch_puc_dockets(state="AZ", list_systems=true) to see all known PUC systems

"What dimensions do you score on?" Answer from this skill — no tool call needed.

Presenting Results

• Lead with composite score and tier label
• Summarize the rationale in 1–2 sentences
• Call out dimensions that drove the score (high or low)
• If confidence is low or dimensions are stale, mention the caveat
• For comparisons, highlight the dimensions where utilities differ most

Weight Suggestions

• User needs to be online in 18 months → suggest boosting interconnection_speed
• User has no clean energy mandate → suggest zero-weighting clean_energy_posture
• User is hyperscale campus → default weights are fine; use_case affects rationale tone

Limitations to Mention When Relevant

• Private negotiations — Score reflects visible filings; special contracts filed under seal are invisible
• State vs. utility — Low regulatory_environment may reflect state constraints, not utility willingness
• Municipal/coop — Limited public data; expect low confidence
• Geographic variability — Score is utility-level, not substation-level; Charlotte vs. rural NC may differ