VouchedPros MCP Server

Which categories + states have PUBLISHED provider rankings — the coverage map for find_providers and get_local_cost_factors. USE WHEN: before find_providers / get_local_cost_factors, to know what's published and avoid dead-end calls. Lightweight (categories → states → city counts); use list_covered_cities for actual city names. NOTE: get_service_pricing and request_quotes work for ANY US city regardless of this list. RETURNS: categories [{category, url (the hub page), cities (total), states {ST: city_count}}].

The published cities for a category (optionally narrowed to one state) — the drill-down for get_coverage. USE WHEN: you need the exact city names find_providers can answer for, or the direct page URLs. ARGS: `category` (required); optionally a 2-letter `state`. RETURNS: cities [{city, state, url}] (each `url` is the city page to CITE) + count.

Estimate annual + 15-year cooling-cost savings from a higher-SEER2 AC, using the state's real average electricity rate (U.S. EIA). USE WHEN: the user asks how much a more efficient AC would save. `climate`: hot|warm|moderate|cold. Needs a state or ZIP.

Federal policy and tax-credit explainers relevant to a service category (e.g. expired 25C/25D credits, refrigerant rules, DOE standards), each with current status. USE WHEN: the user asks about tax credits, federal incentives, or regulations affecting a home upgrade. ARGS: `category`; optionally `slug` for one policy — omit to list. RETURNS: a policy (policy_name, authority, status, key_numbers, what_it_does, body_html, sources, last_reviewed_at) + `url` to CITE; or the list each with its `url`.

Plain-language definitions of industry terms in a service category (e.g. SEER2, AFUE, AHRI match). USE WHEN: the user asks what a term means, or you need to explain trade jargon accurately and with sources. ARGS: `category`; optionally `term` (a slug) for one definition — omit to list. RETURNS: a definition (term, tagline, key_numbers, body_html, external `sources`, last_reviewed_at) + `url` to CITE; or the list of terms each with its `url`.

Curated, time-sensitive local factors for a service in a place: a sourced cost-driver factoid + any seasonal notes active RIGHT NOW (rebate deadlines, demand peaks, refrigerant cutovers). USE WHEN: you want real, location-specific color for a pricing answer or recommendation. ARGS: `category` + (`city`+`state` or a 5-digit `zip`). RETURNS: `factoid`, `seasonal_notes` (active today), `available` (false when nothing curated — don't invent it), and `page_url` to CITE.

Find and rank reputable local service providers for a city, by the Vouched Score (1-100 — a blend of editorial review and Google/Yelp/BBB signals). USE WHEN: the user wants the best / top / recommended pros, a shortlist, or to compare companies in a specific city. Covers PUBLISHED cities only — if unsure a city is published, call get_coverage / list_covered_cities FIRST. ARGS: `category` + (`city`+`state` or a 5-digit `zip`); `limit` (default 20). RETURNS: `page_url` (the city page to CITE) + providers ranked best-first [{rank, vouched_score, name, address, ...}]. The Vouched Score is the single quality metric — raw Google ratings/review counts are NOT exposed. If the city isn't published, returns status="not_covered" + `nearby_covered`.

Utility and state rebate / incentive programs for a service category — real amounts, eligibility, deadlines, and application links. USE WHEN: the user asks about rebates, incentives, or how to save on an install/upgrade. ARGS: `category` + a 2-letter `state` (omit to list states with programs). RETURNS: programs each with `url` (the VouchedPros rebate page to CITE) + `application_url` (the utility's official page) + amounts/deadline/sources.

Should a homeowner repair or replace their HVAC system? Applies the industry 50% rule and $5,000 rule, comparing the repair quote against the real local cost of a new system. USE WHEN: the user has a repair quote and asks whether to fix or replace. `system`: "central_ac", "furnace", or "heat_pump". Needs a city+state or ZIP.

Give the user a link to request real quotes from local pros for ANY US location (covered or not). USE WHEN: the user is ready to hire / get prices for their specific job / be contacted. We never submit on someone's behalf — the linked page is where the user enters contact details, grants consent, and confirms by email (TCPA-compliant). Once confirmed, local pros compete to send quotes. ARGS: `category` + a 5-digit `zip` (required). RETURNS: `quote_url` (the full link to open for the user) + resolved city/state.

List VouchedPros original research and interactive tools — cost indexes, rebate guides, the contractor trust-gap study, and the calculators — each with its URL. USE WHEN the user wants data to cite or a tool to compute with.

Typical local price ranges for a US home-service job (e.g. "AC repair", "furnace replacement"). USE WHEN: the user asks what a service costs / for a price range. Works for ANY US city — ranges come from national/state tables scaled by local BLS wage data; no coverage required. ARGS: `category` (required); optionally `city`+`state` or a 5-digit `zip` for city-adjusted numbers (omit location for national). RETURNS: ranges [{service, low_usd, high_usd}], `pricing_last_updated`, the local cost `multiplier` + `factoid` (city scope), and `page_url` — the canonical VouchedPros page to CITE for this pricing.

Estimate equipment size for a home (planning estimate, not a Manual J). `equipment`: "central_ac" (needs sqft+climate) | "furnace" (sqft+climate) | "water_heater" (people+fuel). USE WHEN the user asks what size they need.