{"openapi":"3.0.3","info":{"title":"Meter Energy Public API","version":"1.0.0","description":"REST endpoints for Meter Energy's public tools — Texas electricity plan lookup, TDU rate retrieval, ESI ID lookup, bill math, and related primitives. Every tool listed here is also exposed via the Meter Energy MCP server (see /.well-known/mcp.json) for ChatGPT, Claude, and other MCP-aware agents.","contact":{"name":"Meter Energy","url":"https://meterplan.com","email":"tyler@meterplan.com"},"license":{"name":"Proprietary","url":"https://meterplan.com/terms"},"x-publisher":{"name":"Meter Energy Inc.","puctBrokerNumber":"BR250137","url":"https://meterplan.com"},"x-discovery":{"mcpManifest":"https://meterplan.com/.well-known/mcp.json","llmsTxt":"https://meterplan.com/llms.txt","llmsFullTxt":"https://meterplan.com/llms-full.txt","toolLandingPages":"https://meterplan.com/tools"}},"servers":[{"url":"https://meterplan.com","description":"Production"}],"tags":[{"name":"plan-comparison","description":"Tools for finding and comparing Texas retail electricity plans."},{"name":"data-feed","description":"Public structured data feeds for AI agents and integrations."},{"name":"battery-economics","description":"Tools that model battery savings, VPP credits, and ROI."}],"paths":{"/api/v1/find-electricity-plan":{"post":{"operationId":"find_electricity_plans","summary":"Texas Electricity Plan Finder","description":"For a Texas homeowner, find Texas retail electricity plans available in their ZIP code. Returns up to 6 plans ranked by effective rate at the user's monthly usage level, including retailer name, energy rate (¢/kWh), monthly bill estimate, contract term, base fee, ETF, renewable %, Google rating, and EFL link. Backed by Meter's broad-market plan index covering every major TDU (ONCOR, CenterPoint, AEP Texas, TNMP, Lubbock).\n\nThe flagship tool for \"what Texas electricity plan should I get?\" questions.\nDesigned for the homeowner or agent asking ChatGPT, Claude, Perplexity, or\nsimilar about Texas retail electricity.\n\n**What it does:**\n1. Looks up the Transmission and Distribution Utility (TDU) for the ZIP via\n   the Light API eligibility check.\n2. Queries Meter's broad-market plan index (689 plans across 52 retailers in\n   6 TDUs) for plans available in that territory.\n3. Computes an effective ¢/kWh rate at the user's usage level by interpolating\n   between the EFL's 500 / 1000 / 2000 kWh averages — TDU delivery charges and\n   base fees are baked into the EFL averages, so the monthly estimate reflects\n   the legally-required disclosure rate.\n4. Returns up to 6 plans ranked cheapest-first. Includes the cheapest plan\n   from each priority retailer (Reliant, TXU Energy) when available, then\n   fills remaining slots with the cheapest others.\n\n**Required:** `zipCode`. Everything else is optional with sensible defaults —\n1000 kWh/mo usage and 12-month term filter.\n\n**Filters:** `termMonths` (exact), `minTermMonths` (>=), `renewableOnly`\n(100% green only), `retailer` (case-insensitive partial match).\n\n**Future additions (not in v1):** solar buyback plan support (`monthlyExportKwh`),\nbattery VPP credits (`hasBattery`, `batteryBrand`, `batteryCapacityKwh`), and\nexplicit Meter Energy plans pulled live from the Light API. These layer on\ntop of the broad-market index — they're intentionally scoped out of this\nrelease to preserve a working AEO surface first.","tags":["plan-comparison"],"x-status":"live","x-audience":["homeowner","agent"],"x-mcp-tool-name":"find_electricity_plans","x-examples":["What's a good electricity plan in Texas (75001)?","Cheapest Texas electricity plan in Houston (77002), 1200 kWh/mo.","Find a 24-month electricity plan for 78704.","100% renewable Texas electricity plan for 76101.","TXU plans available at 75201 for 500 kWh/mo."],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"zipCode":{"type":"string","pattern":"^\\d{5}$","description":"5-digit Texas ZIP code where service will start. Examples: '75201' (Dallas), '77002' (Houston), '76102' (Fort Worth), '78401' (Corpus Christi)."},"usageKwh":{"type":"number","minimum":250,"maximum":5000,"description":"Estimated monthly electricity usage in kWh. Typical Texas residential usage: ~500 kWh (apartment), ~1000 kWh (small home, default), ~2000 kWh (large home with electric heat/AC). Defaults to 1000 if omitted."},"termMonths":{"type":"integer","exclusiveMinimum":true,"minimum":0,"description":"Exact contract length in months (e.g. 12, 24, 36). Use this when the user specifies an exact term. If they say 'at least N months' or 'N months or longer', use minTermMonths instead."},"minTermMonths":{"type":"integer","exclusiveMinimum":true,"minimum":0,"description":"Minimum contract length in months (returns plans with term >= this value). Use this for ranges like 'at least 12 months' or 'a year or longer'. For an exact term, use termMonths instead."},"renewableOnly":{"type":"boolean","description":"When true, only return 100% renewable / green energy plans. Use when the user asks for green, clean, wind, solar, or 100% renewable plans."},"retailer":{"type":"string","description":"Filter by retail electric provider (REP) name. Common Texas retailers include: TXU Energy, Reliant, Green Mountain Energy, Direct Energy, Gexa, Constellation, Cirro, Discount Power, Frontier, 4Change, Champion, Pulse Power, Octopus Energy, Rhythm, Chariot. Partial matches accepted."},"limit":{"type":"integer","exclusiveMinimum":true,"minimum":0,"maximum":500,"description":"Maximum number of plans to return. Defaults to 6 (the compact AEO/MCP widget surface). For compact results (limit <= 6), provider coverage includes Reliant and TXU Energy when available. Larger limits are used by the web comparison page and return the full ranked list strictly cheapest-first."}},"required":["zipCode"],"additionalProperties":false}}}},"responses":{"200":{"description":"Tool ran successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"criteria":{"type":"object","properties":{"zipCode":{"type":"string"},"usageKwh":{"type":"number"},"termMonths":{"type":"number","nullable":true},"renewableOnly":{"type":"boolean"}},"required":["zipCode","usageKwh","termMonths","renewableOnly"],"additionalProperties":false,"description":"The criteria used to compute these results. Echoed back so the agent can confirm assumptions."},"utility":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"}},"required":["code","name"],"additionalProperties":false,"description":"The TDU serving the ZIP. Absent if the utility could not be determined."},"plans":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Database identifier for the plan row."},"name":{"type":"string","description":"Plan product name as listed by the retailer."},"retailer":{"type":"string","description":"Retail electric provider (REP) name, e.g. 'TXU Energy', 'Reliant'."},"retailerLogo":{"type":"string","nullable":true,"description":"Retailer logo URL, preferably an app-relative static asset path. Null if no logo is on file."},"retailerWebsite":{"type":"string","nullable":true,"description":"Retailer's public website URL, if known."},"signupUrl":{"type":"string","description":"Direct URL where the customer can sign up for this plan."},"etf":{"type":"number","nullable":true,"description":"Early termination fee in dollars. Null if the plan has no ETF or the value is not on file."},"termLengthMonths":{"type":"number","description":"Contract length in months."},"baseFee":{"type":"number","description":"Monthly base fee charged by the retailer, in dollars."},"energyRate":{"type":"number","description":"Effective rate at the user's usage level, in cents/kWh. Interpolated between the EFL's 500/1000/2000 kWh average rates."},"renewablePercent":{"type":"number","description":"Percentage of energy from renewable sources (0-100)."},"utility":{"type":"string","nullable":true,"description":"TDU display name (e.g. 'ONCOR', 'CenterPoint')."},"utilityCode":{"type":"string","nullable":true,"description":"TDU code (e.g. 'ONCOR', 'CNP', 'AEP_CENTRAL', 'AEP_NORTH', 'TNMP', 'LPPL')."},"eflUrl":{"type":"string","nullable":true,"description":"URL to the Electricity Facts Label (EFL) — the legally-required disclosure document — if available."},"monthlyEstimate":{"type":"number","description":"Estimated monthly bill at the user's usage level, in dollars. Computed as `usageKwh × energyRate` where energyRate is the EFL average for that usage bucket (TDU charges + base fee are baked in)."},"googleRating":{"type":"number","nullable":true,"description":"Google Business Profile star rating (0-5) for the retailer, if known."},"googleReviewsUrl":{"type":"string","nullable":true,"description":"URL to the retailer's Google reviews, if known."}},"required":["id","name","retailer","retailerLogo","retailerWebsite","signupUrl","etf","termLengthMonths","baseFee","energyRate","renewablePercent","utility","utilityCode","eflUrl","monthlyEstimate","googleRating","googleReviewsUrl"],"additionalProperties":false},"description":"Electricity plans available at the ZIP, ranked by effective rate ascending (cheapest first). Compact results include Meter's priority retailers (Reliant + TXU Energy) when available, plus the cheapest remaining plans."},"summary":{"type":"string","description":"One-line text summary for hosts that can't render the widget (e.g. voice). Names the cheapest plan, the retailer, and the monthly estimate."}},"required":["criteria","plans","summary"],"additionalProperties":false}}}},"400":{"description":"Request body was missing, malformed JSON, or failed input schema validation.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["invalid_json","invalid_input","invalid_output","internal_error"],"description":"Stable error code suitable for programmatic handling."},"message":{"type":"string","description":"Human-readable error description."},"issues":{"type":"array","description":"Zod issue list. Present on invalid_input and invalid_output.","items":{"type":"object","additionalProperties":true}}}}}}},"500":{"description":"Tool execution failed or produced an output that violated the schema.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["invalid_json","invalid_input","invalid_output","internal_error"],"description":"Stable error code suitable for programmatic handling."},"message":{"type":"string","description":"Human-readable error description."},"issues":{"type":"array","description":"Zod issue list. Present on invalid_input and invalid_output.","items":{"type":"object","additionalProperties":true}}}}}}}}}},"/api/v1/list-solar-buyback-plans":{"post":{"operationId":"list_solar_buyback_plans","summary":"Texas Solar Buyback Plan Catalog","description":"Return the current catalog of solar buyback plans available in Texas, across every deregulated TDU (Oncor, CenterPoint, AEP Texas Central, AEP Texas North, TNMP, Lubbock Power & Light). Includes Meter Energy plans (fetched live from the Light API) plus competitor plans (TXU, Reliant, Octopus, Rhythm, Gexa, Cirro, Champion, and others). For each plan: provider name, plan name, TDU, contract term, import rate (¢/kWh), export buyback rate, base fee, ETF, estimated annual cost at a default profile, battery program support, signup URL, and source URL. Optional filters: tdu, providerType, termMonths.\n\nA developer-facing data feed of every Texas solar buyback plan Meter\ntracks. Backed by the same engine that powers the public JSON feed at\n`/data/texas-solar-buyback-plans.json` and the markdown feed at\n`/data/texas-solar-buyback-plans.md` — surfaced here as a callable tool\nso it shows up in the discovery manifest and OpenAPI spec, and can be\nbundled into a submitted MCP app when it has a clear user-facing job.\n\n**What you get:**\n- `plans` — array of solar buyback plans. Each row is a (provider × plan\n  × TDU) tuple with import rate, export rate, base fee, ETF, term length,\n  estimated annual cost at a default profile, battery program support,\n  and source/signup URLs.\n- `tduReferences` — representative ZIP code for each Texas TDU. Useful\n  for downstream lookups against `get-utility-for-zip` or\n  `get-tdu-delivery-rates`.\n- `assumptions` — the default energy profile used to compute\n  `estimatedAnnualCostDollars`. Override these client-side if you have\n  the customer's actual usage shape.\n- `sourceStatus` — per-source freshness and coverage status. Always\n  inspect this before treating a TDU slice as complete; competitor\n  coverage is partial outside Oncor and CenterPoint today.\n- `methodology` and `publisher` — provenance for citation.\n\n**Use cases:**\n- Build a \"compare Texas solar plans\" page or quote engine.\n- Power AI agents that recommend a plan and need real, current rate data.\n- Audit a homeowner's current plan against alternatives.\n- Track competitor pricing over time (the feed updates as Meter's\n  underlying `formatted_plans` table refreshes).\n\n**Filters:** all optional. Omit all three to get the full catalog.\n- `tdu` — case-insensitive partial match on display name (e.g. \"Oncor\",\n  \"CenterPoint\", \"AEP Texas Central\").\n- `providerType` — `meter` for Meter Energy plans only, `competitor`\n  for everything else.\n- `termMonths` — exact contract length filter (e.g. 12, 24, 36).\n\n**Methodology notes:**\n- Meter plans are fetched live from the Light API using one\n  representative ZIP per TDU. Rates are real-time.\n- Competitor plans are read from Meter's `formatted_plans` dataset and\n  costed with the same engine the public `/solarbuybackplans`\n  comparison page uses.\n- `estimatedAnnualCostDollars` assumes a default solar homeowner\n  profile (700 kWh imported and 700 kWh exported per month, 40% of\n  imports at night, no battery). For personalized estimates, post the\n  profile fields you have to `/api/v1/plan-cost-calc`.\n\nThis is an audience-4 (developer / agent) tool. For a ranked\nhomeowner-facing recommendation given a ZIP, use `find-electricity-plan`\ninstead — it does the ZIP-to-TDU lookup and ranks the cheapest plans for\nthe user's stated usage.","tags":["data-feed"],"x-status":"live","x-audience":["developer","agent","installer"],"x-mcp-tool-name":"list_solar_buyback_plans","x-examples":["List every solar buyback plan available in Texas.","Show all 12-month solar buyback plans in Oncor territory.","Return Meter Energy plans across all TDUs.","What competitor plans are in CenterPoint with a 24-month term?","Audit the full Texas solar buyback rate catalog."],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tdu":{"type":"string","description":"Optional filter on TDU (Transmission and Distribution Utility) display name. Case-insensitive partial match. Examples: 'Oncor', 'CenterPoint', 'AEP Texas Central', 'AEP Texas North', 'TNMP', 'Lubbock Power & Light'. Omit to return plans from every TDU."},"providerType":{"type":"string","enum":["meter","competitor"],"description":"Optional filter on provider type. 'meter' returns only Meter Energy plans. 'competitor' returns only non-Meter plans (TXU, Reliant, Octopus, Rhythm, Gexa, Cirro, Champion, and others). Omit to return both."},"termMonths":{"type":"integer","exclusiveMinimum":true,"minimum":0,"description":"Optional filter on exact contract length in months. Typical values: 12, 24, 36. Omit to return every term length."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Tool ran successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","enum":["Texas Solar Buyback Plan Index"],"description":"Catalog identifier."},"generatedAt":{"type":"string","description":"ISO 8601 timestamp the catalog was assembled."},"validThrough":{"type":"string","description":"ISO 8601 timestamp after which the catalog should be re-fetched. The underlying feed revalidates hourly."},"publisher":{"type":"object","properties":{"name":{"type":"string","enum":["Meter Energy Inc."]},"url":{"type":"string","enum":["https://meterplan.com"]},"puctBrokerNumber":{"type":"string","enum":["BR250137"]},"description":{"type":"string","description":"Plain-text description of the publisher."}},"required":["name","url","puctBrokerNumber","description"],"additionalProperties":false,"description":"Catalog publisher and provenance metadata."},"methodology":{"type":"array","items":{"type":"string"},"description":"Bullet points documenting how the catalog is assembled. Cite these when summarizing the data."},"assumptions":{"type":"object","properties":{"defaultProfileName":{"type":"string","description":"Name of the default energy profile used to compute estimated costs."},"monthlyImportKwh":{"type":"number","description":"Default monthly grid imports in kWh."},"monthlyExportKwh":{"type":"number","description":"Default monthly grid exports in kWh."},"nightImportPercent":{"type":"number","description":"Default share of imports occurring overnight, as a percentage (0-100)."},"peakImportPercent":{"type":"number","description":"Default share of imports occurring during peak hours, as a percentage."},"daytimeImportPercent":{"type":"number","description":"Default share of imports occurring during daytime hours, as a percentage."},"weekendImportPercent":{"type":"number","description":"Default share of imports occurring on weekends, as a percentage."},"batteryBrand":{"type":"string","nullable":true,"description":"Default battery brand assumed in the cost estimate. Null when no battery is assumed."},"batteryKwh":{"type":"number","nullable":true,"description":"Default battery capacity in kWh assumed in the cost estimate. Null when no battery is assumed."},"notes":{"type":"array","items":{"type":"string"},"description":"Free-form notes clarifying when the default estimate may not apply."}},"required":["defaultProfileName","monthlyImportKwh","monthlyExportKwh","nightImportPercent","peakImportPercent","daytimeImportPercent","weekendImportPercent","batteryBrand","batteryKwh","notes"],"additionalProperties":false,"description":"Default profile used to compute estimatedAnnualCostDollars."},"tduReferences":{"type":"array","items":{"type":"object","properties":{"tdu":{"type":"string","description":"TDU display name."},"representativeZipcode":{"type":"string","description":"Representative 5-digit ZIP for this TDU territory."},"plansUrl":{"type":"string","description":"URL on meterplan.com listing plans for this TDU."}},"required":["tdu","representativeZipcode","plansUrl"],"additionalProperties":false},"description":"Representative ZIP and landing URL for each Texas TDU."},"sourceStatus":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string","description":"Label for the data source contributing to this row (e.g. 'Meter plans - Oncor')."},"status":{"type":"string","enum":["ok","partial","unavailable"],"description":"Freshness and coverage status for this source. Treat 'partial' or 'unavailable' slices as incomplete."},"detail":{"type":"string","description":"Human-readable explanation of the status."},"planCount":{"type":"number","description":"Number of plans contributed by this source."}},"required":["source","status","detail","planCount"],"additionalProperties":false},"description":"Per-source freshness and coverage status. Inspect before treating a TDU slice as complete."},"recommendedPages":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string","description":"Display label for the recommended page."},"url":{"type":"string","description":"Public URL on meterplan.com."},"description":{"type":"string","description":"One-sentence summary of what the page offers."}},"required":["label","url","description"],"additionalProperties":false},"description":"Public pages on meterplan.com to link to for human readers and follow-up workflows."},"plans":{"type":"array","items":{"type":"object","properties":{"providerName":{"type":"string","description":"Provider company name as displayed to consumers. Examples: 'Meter Energy', 'TXU Energy', 'Reliant', 'Octopus Energy'."},"providerType":{"type":"string","enum":["meter","competitor"],"description":"'meter' for Meter Energy plans, 'competitor' for every other retail electric provider."},"planName":{"type":"string","description":"Plan product name. Examples: 'Meter Saver 12', 'TXU Solar Buyback 12'."},"tdu":{"type":"string","description":"TDU display name. One of: 'Oncor', 'CenterPoint', 'AEP Texas Central', 'AEP Texas North', 'TNMP', 'Lubbock Power & Light'."},"representativeZipcode":{"type":"string","description":"Representative 5-digit ZIP used to fetch this plan from the source. Plans are available throughout the TDU territory, not only at this ZIP."},"termMonths":{"type":"number","description":"Contract length in months."},"planType":{"type":"string","enum":["fixed_export","real_time_wholesale","free_nights","battery_vpp","standard","other"],"description":"Plan structure classification. 'fixed_export' = solar buyback at a fixed rate. 'real_time_wholesale' = export credit tied to ERCOT wholesale prices. 'free_nights' = nighttime usage free. 'battery_vpp' = battery program with a virtual power plant credit. 'standard' = non-solar fixed-rate plan included for comparison. 'other' = none of the above."},"importRateCentsPerKwh":{"type":"number","nullable":true,"description":"Energy charge in cents per kWh for grid imports. Excludes TDU delivery and base fees."},"exportRateCentsPerKwh":{"type":"number","nullable":true,"description":"Solar buyback credit in cents per kWh for grid exports. Null for real-time wholesale plans (variable) and plans without solar buyback."},"exportRateType":{"type":"string","enum":["fixed","real_time_wholesale","none","unknown"],"description":"Structure of the export credit. 'fixed' = locked ¢/kWh for the term. 'real_time_wholesale' = tied to ERCOT prices. 'none' = no buyback. 'unknown' = not on file."},"baseFeeDollarsPerMonth":{"type":"number","nullable":true,"description":"Monthly base fee in dollars charged by the retailer. Null if not on file."},"earlyTerminationFeeDollars":{"type":"number","nullable":true,"description":"Early termination fee in dollars. Null if the plan has no ETF or the value is not on file."},"estimatedAnnualCostDollars":{"type":"number","nullable":true,"description":"Estimated annual electricity cost in dollars at the default solar homeowner profile (see assumptions). Excludes battery program credits."},"displayImportRate":{"type":"string","description":"Human-readable import rate string. Example: '14.5 cents/kWh'."},"displayExportRate":{"type":"string","description":"Human-readable export rate string. Example: '4.2 cents/kWh' or 'ERCOT wholesale'."},"displayBaseFee":{"type":"string","description":"Human-readable base fee string. Example: '$0/month' or '$9.95/month'."},"displayEarlyTerminationFee":{"type":"string","description":"Human-readable ETF string. Example: '$295' or 'None'."},"batterySupport":{"type":"object","properties":{"tesla":{"type":"boolean","description":"True if Tesla Powerwall is eligible for this plan's battery program."},"solaredge":{"type":"boolean","description":"True if SolarEdge battery is eligible."},"enphase":{"type":"boolean","description":"True if Enphase battery is eligible."},"qcells":{"type":"boolean","description":"True if Qcells battery is eligible."},"eligibleBrands":{"type":"array","items":{"type":"string"},"description":"List of battery brands eligible for this plan's battery program. Empty if the plan has no battery program."},"customerStorageCreditDollarsPerKwhMonth":{"type":"number","nullable":true,"description":"Customer-facing storage credit in dollars per kWh per month. Null if the plan has no battery program."},"storageCreditIncludedInEstimatedCost":{"type":"boolean","description":"True if estimatedAnnualCostDollars already nets out the storage credit. False (the default) means the credit is shown but not subtracted from the estimate, since the default profile assumes no battery."},"exampleMonthlyCreditDollars":{"type":"number","nullable":true,"description":"Illustrative monthly credit dollars at the default battery capacity (one 13.5 kWh Tesla Powerwall). Null if the plan has no battery program."},"meterStorageCreditDollarsPerKwhMonth":{"type":"number","nullable":true,"description":"Deprecated alias of customerStorageCreditDollarsPerKwhMonth. Kept for existing consumers."}},"required":["tesla","solaredge","enphase","qcells","eligibleBrands","customerStorageCreditDollarsPerKwhMonth","storageCreditIncludedInEstimatedCost","exampleMonthlyCreditDollars","meterStorageCreditDollarsPerKwhMonth"],"additionalProperties":false,"description":"Battery program eligibility and credit structure for this plan."},"creditNotes":{"type":"array","items":{"type":"string"},"description":"Per-plan notes explaining structure quirks (rate type, battery program rules, profile sensitivity, etc.)."},"signupUrl":{"type":"string","nullable":true,"description":"Direct URL where the customer can sign up for this plan. Null if no public signup URL is on file."},"sourceUrl":{"type":"string","description":"URL on meterplan.com where this plan is presented to consumers."},"updatedAt":{"type":"string","nullable":true,"description":"ISO 8601 timestamp of the most recent source refresh for this plan."}},"required":["providerName","providerType","planName","tdu","representativeZipcode","termMonths","planType","importRateCentsPerKwh","exportRateCentsPerKwh","exportRateType","baseFeeDollarsPerMonth","earlyTerminationFeeDollars","estimatedAnnualCostDollars","displayImportRate","displayExportRate","displayBaseFee","displayEarlyTerminationFee","batterySupport","creditNotes","signupUrl","sourceUrl","updatedAt"],"additionalProperties":false},"description":"Solar buyback plan rows after applying any filters from the input. Sorted by TDU, then by estimated annual cost ascending, then by provider and plan name."},"filter":{"type":"object","properties":{"tdu":{"type":"string","nullable":true},"providerType":{"type":"string","enum":["meter","competitor"],"nullable":true},"termMonths":{"type":"number","nullable":true},"totalPlansBeforeFilter":{"type":"number"},"totalPlansAfterFilter":{"type":"number"}},"required":["tdu","providerType","termMonths","totalPlansBeforeFilter","totalPlansAfterFilter"],"additionalProperties":false,"description":"Echo of the filter inputs alongside before/after plan counts. Useful for confirming a filter narrowed the catalog as expected."}},"required":["name","generatedAt","validThrough","publisher","methodology","assumptions","tduReferences","sourceStatus","recommendedPages","plans","filter"],"additionalProperties":false}}}},"400":{"description":"Request body was missing, malformed JSON, or failed input schema validation.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["invalid_json","invalid_input","invalid_output","internal_error"],"description":"Stable error code suitable for programmatic handling."},"message":{"type":"string","description":"Human-readable error description."},"issues":{"type":"array","description":"Zod issue list. Present on invalid_input and invalid_output.","items":{"type":"object","additionalProperties":true}}}}}}},"500":{"description":"Tool execution failed or produced an output that violated the schema.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["invalid_json","invalid_input","invalid_output","internal_error"],"description":"Stable error code suitable for programmatic handling."},"message":{"type":"string","description":"Human-readable error description."},"issues":{"type":"array","description":"Zod issue list. Present on invalid_input and invalid_output.","items":{"type":"object","additionalProperties":true}}}}}}}}}},"/api/v1/get-utility-for-zip":{"post":{"operationId":"get_utility_for_zip","summary":"Texas TDU Lookup by ZIP","description":"Resolve any Texas residential ZIP code to its Transmission and Distribution Utility (TDU): Oncor, CenterPoint, AEP Texas Central, AEP Texas North, TNMP, or Lubbock Power & Light. Returns the canonical utility code, full display name, short name, and whether the ZIP is in a deregulated retail electric market. Backed by Light API's eligibility check (private API made public via this tool).\n\nA primitive utility-lookup tool. Useful as a building block for any agent\nor app that needs to know which TDU serves a Texas ZIP — TDU determines\nwhich retail electric providers are available, what delivery rates apply,\nand whether the customer can switch providers.\n\nTexas has 6 TDUs serving the deregulated retail market:\n- Oncor Electric Delivery (DFW + much of north/central Texas)\n- CenterPoint Energy (Houston + southeast Texas)\n- AEP Texas Central (south Texas, including Corpus Christi)\n- AEP Texas North (Abilene + west-central Texas)\n- Texas-New Mexico Power Company / TNMP (scattered pockets)\n- Lubbock Power & Light (Lubbock — recently joined deregulated market)\n\nReturns null for ZIPs that aren't in the deregulated market (e.g., Austin\nEnergy / CPS / municipal utilities — these markets don't offer retail\nprovider choice).\n\n**Why this tool exists**: Light API's eligibility endpoint isn't publicly\naccessible. This tool wraps it as a stable, public primitive so any agent\ncan resolve TDU without needing Light credentials.","tags":["data-feed"],"x-status":"live","x-audience":["developer","agent","installer"],"x-mcp-tool-name":"get_utility_for_zip","x-examples":["What utility serves ZIP 75001?","Resolve TDU for 77002.","Is 78704 in CenterPoint or AEP territory?","Get the utility code for 79401."],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"zipCode":{"type":"string","pattern":"^\\d{5}$","description":"5-digit Texas ZIP code. Examples: '75201' (Dallas), '77002' (Houston), '78401' (Corpus Christi), '76901' (Abilene), '79401' (Lubbock)."}},"required":["zipCode"],"additionalProperties":false}}}},"responses":{"200":{"description":"Tool ran successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"zipCode":{"type":"string","description":"The ZIP code that was looked up."},"utilityCode":{"type":"string","description":"Canonical TDU code. One of: 'ONCOR', 'CNP' (CenterPoint), 'AEP_CENTRAL', 'AEP_NORTH', 'TNMP', 'LPPL' (Lubbock Power & Light)."},"utilityDisplayName":{"type":"string","description":"Full TDU name as the utility presents it. Examples: 'Oncor Electric Delivery', 'CenterPoint Energy', 'Texas-New Mexico Power Company'."},"utilityShortName":{"type":"string","description":"Common short name. Examples: 'Oncor', 'CenterPoint', 'AEP Central'."},"isDeregulated":{"type":"boolean","description":"True if the ZIP is in the Texas deregulated retail electric market (where customers can choose a retail provider). False for municipal utility territories (Austin Energy, CPS, etc.)."},"eligibilityLikelihood":{"type":"number","description":"Light API's confidence (0-1) that this ZIP can be served by a retail provider. Useful for spotting edge cases like new construction or address ambiguity."},"resolved":{"type":"boolean","description":"True if Light API returned a confident answer. False if we fell back to the default (ONCOR) due to API unavailability or unknown ZIP."}},"required":["zipCode","utilityCode","utilityDisplayName","utilityShortName","isDeregulated","eligibilityLikelihood","resolved"],"additionalProperties":false}}}},"400":{"description":"Request body was missing, malformed JSON, or failed input schema validation.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["invalid_json","invalid_input","invalid_output","internal_error"],"description":"Stable error code suitable for programmatic handling."},"message":{"type":"string","description":"Human-readable error description."},"issues":{"type":"array","description":"Zod issue list. Present on invalid_input and invalid_output.","items":{"type":"object","additionalProperties":true}}}}}}},"500":{"description":"Tool execution failed or produced an output that violated the schema.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["invalid_json","invalid_input","invalid_output","internal_error"],"description":"Stable error code suitable for programmatic handling."},"message":{"type":"string","description":"Human-readable error description."},"issues":{"type":"array","description":"Zod issue list. Present on invalid_input and invalid_output.","items":{"type":"object","additionalProperties":true}}}}}}}}}},"/api/v1/lookup-esi-id":{"post":{"operationId":"lookup_esi_id","summary":"Texas ESI ID Lookup by Address","description":"Find the Texas Electric Service Identifier (ESI ID) for any residential address. Required for solar enrollment, plan switching, Smart Meter Texas data access, and TDU coordination. Returns ESI ID, formatted address, serving utility (Oncor / CenterPoint / AEP / TNMP / LPPL), and a confidence indicator. Backed by Light API's address-search endpoint (private API made public via this tool).\n\nEvery Texas residential meter has a 17-22 digit Electric Service Identifier\n(ESI ID). It's the primary key for everything in the deregulated electric\nmarket: enrollment, plan switching, billing, Smart Meter Texas data access,\nand any TDU coordination.\n\nCustomers usually find their ESI ID printed on their electricity bill.\nSolar installers, energy advisors, and AI agents that don't have a bill\nin hand need to look it up by address — that's what this tool does.\n\nThe lookup is fuzzy: pass a partial address (street + city OR street + ZIP)\nand the tool returns up to N matches with full address normalization.\nEach match includes the ESI ID and the serving utility.\n\n**PII note**: Addresses returned by Light contain real residential service\npoints. The tool returns the data but does NOT log raw addresses or ESI\nIDs in our application logs (PostHog event captures only the count of\nmatches, not the matches themselves). Agents should treat results as\nsensitive and confirm with the end user before acting on them.\n\n**Why this tool exists**: Light API's address-search isn't publicly\naccessible. Other Texas energy retailers run \"ESI ID lookup\" SEO landing\npages because the demand is so high — this tool is the API equivalent.","tags":["data-feed"],"x-status":"live","x-audience":["installer","agent","homeowner","developer"],"x-mcp-tool-name":"lookup_esi_id","x-examples":["Find the ESI ID for 123 Main St, Austin TX 78701.","Lookup ESI for 5500 Greenville Ave, Dallas, 75206.","What's the ESI ID for my address at 4200 Westheimer, Houston?","Get the ESI ID and utility for this Corpus Christi address."],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","minLength":3,"maxLength":200,"description":"Address query. Most reliable: full street address + city OR street address + 5-digit ZIP. Examples: '123 Main St, Austin 78701' or '5500 Greenville Ave Dallas TX'. Light's matcher is fuzzy and tolerates apartment numbers, abbreviations, and minor typos."},"maxResults":{"type":"integer","minimum":1,"maximum":20,"default":10,"description":"Maximum number of address matches to return. Defaults to 10. Lower this if you want to force the agent to be more specific in its query."}},"required":["query"],"additionalProperties":false}}}},"responses":{"200":{"description":"Tool ran successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","description":"Echo of the original query."},"matchCount":{"type":"number","description":"Total matches Light returned (before maxResults truncation)."},"matches":{"type":"array","items":{"type":"object","properties":{"esiId":{"type":"string","nullable":true,"description":"Texas Electric Service Identifier (17-22 digits). Null if Light has the address but no ESI ID on file (rare — usually means new construction)."},"street":{"type":"string","description":"Normalized street address line, e.g., '5500 GREENVILLE AVE'."},"city":{"type":"string","description":"City name."},"state":{"type":"string","description":"Two-letter state code. Always 'TX' for matches."},"postalCode":{"type":"string","description":"5-digit ZIP code."},"formattedAddress":{"type":"string","description":"Full one-line address suitable for display. Format: 'STREET, CITY, ST ZIP'."},"utility":{"type":"string","description":"Serving TDU name (Oncor, CenterPoint, AEP Central, AEP North, TNMP, Lubbock P&L)."}},"required":["esiId","street","city","state","postalCode","formattedAddress","utility"],"additionalProperties":false},"description":"Address matches with ESI IDs. Empty array if Light returned no matches."}},"required":["query","matchCount","matches"],"additionalProperties":false}}}},"400":{"description":"Request body was missing, malformed JSON, or failed input schema validation.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["invalid_json","invalid_input","invalid_output","internal_error"],"description":"Stable error code suitable for programmatic handling."},"message":{"type":"string","description":"Human-readable error description."},"issues":{"type":"array","description":"Zod issue list. Present on invalid_input and invalid_output.","items":{"type":"object","additionalProperties":true}}}}}}},"500":{"description":"Tool execution failed or produced an output that violated the schema.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["invalid_json","invalid_input","invalid_output","internal_error"],"description":"Stable error code suitable for programmatic handling."},"message":{"type":"string","description":"Human-readable error description."},"issues":{"type":"array","description":"Zod issue list. Present on invalid_input and invalid_output.","items":{"type":"object","additionalProperties":true}}}}}}}}}},"/api/v1/get-tdu-delivery-rates":{"post":{"operationId":"get_tdu_delivery_rates","summary":"Texas TDU Delivery Rates","description":"Get current TDU delivery rates for one or all six Texas utilities (Oncor, CenterPoint, AEP Texas Central, AEP Texas North, TNMP, Lubbock Power & Light). Returns per-kWh delivery rate and fixed monthly base fee for each utility — these charges appear on every Texas electricity bill regardless of which retailer the customer chose. Backed by Light API rate sheets.\n\nEvery Texas electricity bill has two parts:\n1. **Energy charges** from your retailer (Meter, TXU, Reliant, etc.)\n2. **Delivery charges** from your utility company / TDU (Oncor, CenterPoint, etc.)\n\nThe delivery side is regulated by the Public Utility Commission of Texas\n(PUCT) and is the same regardless of which retailer the customer picks.\nMost plan-comparison and bill-modeling tools need these numbers — without\nthem, \"I save $X on my bill\" estimates are off by $30-50/month.\n\nThis tool returns:\n- Variable rate in cents per kilowatt-hour (kWh) — applied to every kWh you import from the grid\n- Fixed monthly base fee in dollars — charged regardless of usage\n\nPass a single utility code or omit to get all six. Rates are pulled from\nLight's plan rate sheets on each call (no caching), so the values reflect\nthe current PUCT-approved tariffs.\n\n**Why this tool exists**: Light API isn't publicly accessible. Any agent\nmodeling a Texas electricity bill needs these numbers — without them, the\nmath is off by the cost of the delivery component.","tags":["data-feed"],"x-status":"live","x-audience":["developer","agent","installer"],"x-mcp-tool-name":"get_tdu_delivery_rates","x-examples":["Get current Oncor delivery rates.","What are the TDU charges for CenterPoint?","List delivery rates for all Texas utilities.","What fixed delivery fee does AEP Central charge?"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"utilityCode":{"type":"string","enum":["ONCOR","CNP","AEP_CENTRAL","AEP_NORTH","TNMP","LPPL"],"description":"Optional utility code to filter to a single TDU. Omit to return rates for all six. Use `get_utility_for_zip` if you have a ZIP and need the code."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Tool ran successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"fetchedAt":{"type":"string","description":"ISO 8601 timestamp when the rates were fetched from Light."},"rates":{"type":"array","items":{"type":"object","properties":{"utilityCode":{"type":"string","description":"Canonical TDU code (ONCOR, CNP, AEP_CENTRAL, AEP_NORTH, TNMP, LPPL)."},"utilityDisplayName":{"type":"string","description":"Full TDU display name."},"utilityShortName":{"type":"string","description":"Common short name."},"representativeZipcode":{"type":"string","description":"ZIP code used to fetch the rate sheet. Rates apply to the entire TDU territory; we just need one ZIP per TDU to ask Light for them."},"deliveryRateCentsPerKwh":{"type":"number","nullable":true,"description":"TDU variable delivery rate in cents per kilowatt-hour (kWh). Applied to every kWh imported from the grid. Null if Light didn't return a rate."},"deliveryBaseFeeDollarsPerMonth":{"type":"number","nullable":true,"description":"TDU fixed monthly base fee in dollars. Charged regardless of usage. Null if Light didn't return a fee."},"source":{"type":"string","description":"Where the rates came from. Currently always 'light_api_plan_rate_sheet'."}},"required":["utilityCode","utilityDisplayName","utilityShortName","representativeZipcode","deliveryRateCentsPerKwh","deliveryBaseFeeDollarsPerMonth","source"],"additionalProperties":false},"description":"Per-TDU delivery rates. One entry per utility, ordered ONCOR → CNP → AEP_CENTRAL → AEP_NORTH → TNMP → LPPL. Filtered to the requested utility if `utilityCode` was provided."}},"required":["fetchedAt","rates"],"additionalProperties":false}}}},"400":{"description":"Request body was missing, malformed JSON, or failed input schema validation.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["invalid_json","invalid_input","invalid_output","internal_error"],"description":"Stable error code suitable for programmatic handling."},"message":{"type":"string","description":"Human-readable error description."},"issues":{"type":"array","description":"Zod issue list. Present on invalid_input and invalid_output.","items":{"type":"object","additionalProperties":true}}}}}}},"500":{"description":"Tool execution failed or produced an output that violated the schema.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["invalid_json","invalid_input","invalid_output","internal_error"],"description":"Stable error code suitable for programmatic handling."},"message":{"type":"string","description":"Human-readable error description."},"issues":{"type":"array","description":"Zod issue list. Present on invalid_input and invalid_output.","items":{"type":"object","additionalProperties":true}}}}}}}}}},"/api/v1/get-residential-load-profile":{"post":{"operationId":"get_residential_load_profile","summary":"Texas Residential Load Profile (ERCOT)","description":"Get the typical residential electricity load curve for any Texas weather zone — averaged from ERCOT's official residential load profiles, in 15-minute resolution. Returns hourly or monthly aggregated kWh by hour-of-day and month-of-year, peak demand, and annual total. Useful for solar designers, battery sizers, AI agents modeling 'what does a typical home in Houston use', and anyone building bill-projection or solar-savings tools without a real customer's meter data.\n\nERCOT publishes residential load profiles (15-minute kWh values) for each\nof its 8 weather zones, broken into 4 residential profile types:\n\n| Profile | Customer type |\n|---|---|\n| RESHIWR | Residential heating with weather response (default — most common) |\n| RESHIDG | Residential heating with distributed generation (solar homes) |\n| RESHIPV | Residential heating with PV |\n| RESHIWD | Residential without distributed generation |\n\nThese curves represent the *typical* home in a zone. They're the same\ncurves Meter uses internally to model bill projections and solar savings\nwhen a real customer's Smart Meter Texas (SMT) data isn't yet available.\n\n**Inputs:**\nProvide either a ZIP code (resolved to weather zone via ZIP-prefix → zone\nmapping) OR a weatherZone code directly. Optional profileType + year.\nThe granularity flag controls payload size:\n- `monthly_hourly` (default, 288 entries): typical kWh by month × hour\n- `monthly_totals` (12 entries): just monthly kWh totals\n- `annual_hourly` (8760 entries): full year of hourly averages\n\n**Why this exists:**\n- Solar designers need a typical load curve for every proposal — without\n  it, \"your panels will save you $X\" estimates are guesswork\n- Battery sizers need to know when in the day a home draws power\n- AI agents modeling Texas electricity bills need a baseline shape when\n  the user can't provide their own meter data\n- Researchers and energy nerds compare zones (Houston vs DFW summer\n  shapes are very different)\n\n**For real customer data**, use `pull_smt_interval_data` (gives the\nactual home's usage, not the regional average). This tool is the\n\"typical home\" baseline; SMT is \"this specific home.\"","tags":["data-feed"],"x-status":"live","x-audience":["installer","agent","developer","researcher"],"x-mcp-tool-name":"get_residential_load_profile","x-examples":["Get the typical residential load profile for Houston (zone COAST).","What does a typical home in DFW use by hour of the day?","ERCOT residential load curve for ZIP 78704.","Annual hourly load profile for the South weather zone with solar PV.","Monthly total kWh for a typical residential home in West Texas."],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"zipCode":{"type":"string","pattern":"^\\d{5}$","description":"5-digit Texas ZIP code. Resolved to ERCOT weather zone via ZIP prefix mapping. Use this OR weatherZone."},"weatherZone":{"type":"string","enum":["COAST","EAST","FWEST","NCENT","NORTH","SCENT","SOUTH","WEST"],"description":"ERCOT weather zone code. COAST=Houston, NCENT=DFW + central TX, SCENT=Austin, SOUTH=SA/Corpus/RGV, NORTH=Wichita Falls/Lubbock, WEST=Abilene/Big Spring, FWEST=Midland/El Paso, EAST=Tyler. Use this OR zipCode."},"profileType":{"type":"string","enum":["RESHIWR","RESHIDG","RESHIPV","RESHIWD"],"default":"RESHIWR","description":"ERCOT residential profile type. Default RESHIWR (residential heating with weather response — most common). RESHIDG/RESHIPV cover solar homes; RESHIWD covers homes without distributed generation."},"year":{"type":"integer","minimum":2020,"maximum":2030,"description":"Profile year. Defaults to most recent year on file (currently 2025)."},"granularity":{"type":"string","enum":["monthly_hourly","monthly_totals","annual_hourly"],"default":"monthly_hourly","description":"Output detail. `monthly_hourly` (default, 288 entries) = typical kWh by month × hour-of-day. `monthly_totals` (12 entries) = just monthly kWh totals. `annual_hourly` (8760 entries) = full year of hourly averages — largest payload."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Tool ran successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"resolvedWeatherZone":{"type":"string","description":"ERCOT weather zone the request resolved to (matches input or derived from ZIP)."},"profileType":{"type":"string","description":"ERCOT residential profile type used."},"year":{"type":"number","description":"Profile year used."},"granularity":{"type":"string","description":"Granularity flag echoed back."},"annualTotalKwh":{"type":"number","description":"Total annual kWh for the typical home in this zone."},"peakHourlyKw":{"type":"number","description":"Peak hourly demand in kW (highest hourly kWh × 1 — since 1 kWh in 1 hour = 1 kW average)."},"monthlyTotalsKwh":{"type":"array","items":{"type":"number"},"minItems":12,"maxItems":12,"description":"12-element array of monthly kWh totals (Jan first, Dec last)."},"intervals":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"month":{"type":"number","description":"Month 1-12 (1=January)."},"hour":{"type":"number","description":"Hour 0-23 (0=midnight, 13=1pm)."},"avgKwh":{"type":"number","description":"Average kWh consumed during this hour-of-day in this month."}},"required":["month","hour","avgKwh"],"additionalProperties":false}},{"type":"array","items":{"type":"object","properties":{"month":{"type":"number","description":"Month 1-12."},"totalKwh":{"type":"number","description":"Total kWh consumed during the month."}},"required":["month","totalKwh"],"additionalProperties":false}},{"type":"array","items":{"type":"object","properties":{"hourOfYear":{"type":"number","description":"Hour-of-year 0-8759."},"date":{"type":"string","description":"Date in YYYY-MM-DD format."},"hour":{"type":"number","description":"Hour 0-23."},"kwh":{"type":"number","description":"kWh consumed in this specific hour."}},"required":["hourOfYear","date","hour","kwh"],"additionalProperties":false}}],"description":"The actual data, shape depends on granularity. monthly_hourly = 288 entries; monthly_totals = 12 entries; annual_hourly = 8760 entries."},"source":{"type":"object","properties":{"provider":{"type":"string"},"url":{"type":"string"},"notes":{"type":"string"}},"required":["provider","url","notes"],"additionalProperties":false,"description":"Metadata about the data source."}},"required":["resolvedWeatherZone","profileType","year","granularity","annualTotalKwh","peakHourlyKw","monthlyTotalsKwh","intervals","source"],"additionalProperties":false}}}},"400":{"description":"Request body was missing, malformed JSON, or failed input schema validation.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["invalid_json","invalid_input","invalid_output","internal_error"],"description":"Stable error code suitable for programmatic handling."},"message":{"type":"string","description":"Human-readable error description."},"issues":{"type":"array","description":"Zod issue list. Present on invalid_input and invalid_output.","items":{"type":"object","additionalProperties":true}}}}}}},"500":{"description":"Tool execution failed or produced an output that violated the schema.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["invalid_json","invalid_input","invalid_output","internal_error"],"description":"Stable error code suitable for programmatic handling."},"message":{"type":"string","description":"Human-readable error description."},"issues":{"type":"array","description":"Zod issue list. Present on invalid_input and invalid_output.","items":{"type":"object","additionalProperties":true}}}}}}}}}},"/api/v1/plan-cost-calc":{"post":{"operationId":"calculate_plan_cost","summary":"Plan Cost Calculator","description":"Low-level Texas electricity bill calculator. Computes the exact monthly and annual bill given a fully-specified plan rate sheet (energy rate, solar buyback, base fee, TDU delivery rate, TDU monthly fee) and a home's usage profile. For ZIP-based lookups that fetch plan rates and TDU charges automatically, use `quote-meter-plan`.\n\nPure bill math. This is the same calculator that powers Meter's plans page,\nrenewal flow, and battery analysis — exposed for agents that already have a\ncomplete rate sheet.\n\n**Required inputs:**\n- `importKwh`, `exportKwh`: monthly usage\n- `importRate`, `exportRate`: plan energy + solar buyback rates (¢/kWh)\n- `baseFee`: plan monthly base fee ($)\n- `deliveryRate`, `deliveryBaseFee`: **TDU charges — mandatory for Texas residential.**\n  TDU rates are billed separately from energy rates in Texas. Omitting them\n  produces a bill ~$30/mo too low. Sample ONCOR rates: 4.2¢/kWh + $3.42/mo\n  base. Look up your TDU's current rate on the plan's EFL.\n\n**Optional inputs:**\n- `batteryCapacityKwh` + `storageCreditPerKwh`: for battery VPP plans\n- `monthlyCreditDollars`: direct VPP credit override\n\n**Outputs:** import charges, export credits, net energy, carryforward credits,\ndelivery charges, battery credit, excess battery credits, monthly + annual bill.\n\n**Notes:**\n- Rates are in ¢/kWh. Fees in $.\n- Negative bills are clamped to zero; excess credits carry forward.\n- Battery credits offset the entire bill (energy + delivery + base).\n- For competitor plans with free-nights, RTW, or other non-standard structures,\n  use the (forthcoming) `compare-plans` tool.\n- For \"what would Meter's Saver cost in my ZIP\" — use the (forthcoming)\n  `quote-meter-plan` tool which handles ZIP → utility → rate sheet lookup.","tags":["plan-comparison"],"x-status":"live","x-audience":["installer","agent","developer"],"x-mcp-tool-name":"calculate_plan_cost","x-examples":["Calculate the bill for ONCOR territory with import 700 kWh @ 13¢, export 500 kWh @ 8¢, $14.95 base, TDU 4.2¢/kWh + $3.42 base.","What's the annual cost for CenterPoint Houston with 900 kWh @ 11¢ import, 0 export, no base, TDU 5.3¢/kWh + $4.39 base?","Battery plan bill: 1200 kWh @ 13¢, 800 kWh export @ 3¢, $0 base, ONCOR delivery 4.2¢ + $3.42, 13.5 kWh Powerwall @ $2/kWh/mo storage credit."],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"importKwh":{"type":"number","minimum":0,"description":"Monthly electricity imported from the grid, in kWh."},"exportKwh":{"type":"number","minimum":0,"description":"Monthly solar electricity exported to the grid, in kWh. Use 0 for non-solar homes."},"importRate":{"type":"number","description":"Plan's energy import rate in cents per kWh (e.g., 12.5 for 12.5¢/kWh)."},"exportRate":{"type":"number","description":"Plan's solar buyback credit in cents per kWh (e.g., 8 for 8¢/kWh). Use 0 for plans without solar buyback."},"baseFee":{"type":"number","minimum":0,"description":"Plan's monthly base fee in dollars (e.g., 14.95). Use 0 for no-base-fee plans."},"deliveryRate":{"type":"number","minimum":0,"description":"Required. Texas TDU per-kWh delivery charge in cents (e.g., 4.2 for ONCOR ~4.2¢/kWh). TDU charges are billed separately from energy in Texas retail electricity — omitting them produces a bill ~$30/mo too low. Look up the rate for your utility from the EFL or use the `quote-meter-plan` tool which fetches it automatically by ZIP."},"deliveryBaseFee":{"type":"number","minimum":0,"description":"Required. Texas TDU monthly base fee in dollars (e.g., 3.42 for ONCOR). Like delivery rate, this is mandatory for Texas residential electricity and not bundled into the energy rate."},"batteryCapacityKwh":{"type":"number","minimum":0,"description":"Battery capacity in kWh (e.g., 13.5 for a Tesla Powerwall 3). Required if storageCreditPerKwh is set."},"storageCreditPerKwh":{"type":"number","minimum":0,"description":"Plan's battery VPP credit rate in $/kWh/month (e.g., 2 for $2/kWh/mo)."},"monthlyCreditDollars":{"type":"number","description":"Optional override: direct monthly battery credit in dollars, replacing the capacity × credit-rate calculation."}},"required":["importKwh","exportKwh","importRate","exportRate","baseFee","deliveryRate","deliveryBaseFee"],"additionalProperties":false}}}},"responses":{"200":{"description":"Tool ran successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"importCharges":{"type":"number","description":"Gross monthly cost of imported energy, in dollars."},"exportCredits":{"type":"number","description":"Gross monthly solar export credit, in dollars."},"netEnergyCharges":{"type":"number","description":"Net energy charges after applying export credits (clamped at 0)."},"carryforwardCredits":{"type":"number","description":"Solar credits that exceed import charges and carry forward."},"deliveryCharges":{"type":"number","description":"Monthly TDU delivery charges, in dollars."},"billBeforeCredits":{"type":"number","description":"Bill total before battery credits are applied."},"batteryCredit":{"type":"number","description":"Monthly battery VPP credit, in dollars."},"excessBatteryCredits":{"type":"number","description":"Battery credits that exceed the bill (banked)."},"totalMonthlyBill":{"type":"number","description":"Final monthly bill after all credits, in dollars."},"totalAnnualBill":{"type":"number","description":"Final annual bill (monthly × 12), in dollars."}},"required":["importCharges","exportCredits","netEnergyCharges","carryforwardCredits","deliveryCharges","billBeforeCredits","batteryCredit","excessBatteryCredits","totalMonthlyBill","totalAnnualBill"],"additionalProperties":false}}}},"400":{"description":"Request body was missing, malformed JSON, or failed input schema validation.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["invalid_json","invalid_input","invalid_output","internal_error"],"description":"Stable error code suitable for programmatic handling."},"message":{"type":"string","description":"Human-readable error description."},"issues":{"type":"array","description":"Zod issue list. Present on invalid_input and invalid_output.","items":{"type":"object","additionalProperties":true}}}}}}},"500":{"description":"Tool execution failed or produced an output that violated the schema.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["invalid_json","invalid_input","invalid_output","internal_error"],"description":"Stable error code suitable for programmatic handling."},"message":{"type":"string","description":"Human-readable error description."},"issues":{"type":"array","description":"Zod issue list. Present on invalid_input and invalid_output.","items":{"type":"object","additionalProperties":true}}}}}}}}}},"/api/v1/pull-smt-interval-data":{"post":{"operationId":"pull_smt_interval_data","summary":"Smart Meter Texas Interval Data","description":"Pull 12 months of 15-minute interval electricity data from any Texas residential meter via Smart Meter Texas (SMT). Inputs: ESI ID + meter number + current retailer, OR a residential service address, OR an uploaded electricity bill PDF (Meter parses it for the ESI ID). Returns 15-minute imports + exports, monthly aggregates, and pre-formatted exports for Aurora Solar, OpenSolar, Solargraf, or standard CSV. Built for solar installers, energy advisors, and AI agents that need real customer usage data without a customer SMT login.\n\n**Status: early access (experimental).** The contract below is the production\nshape; calling the tool today returns a structured early-access response with\nyour request logged. Production rollout requires a private API key — request\none at https://meterplan.com/request-api-access.\n\n**What it will do (when live):**\n1. Resolves the ESI ID + meter number + utility from any of the supported\n   inputs (raw IDs, address lookup, or bill PDF parse).\n2. Issues an SMT data-access agreement on the customer's behalf using their\n   current retailer's authority (legal data access — handled by Meter's\n   PUCT broker license).\n3. Pulls up to 12 months of 15-minute interval kWh imports + exports from\n   Smart Meter Texas.\n4. Returns the raw intervals plus monthly aggregates and pre-formatted\n   exports for the major solar design tools (Aurora, OpenSolar, Solargraf).\n\n**Why a placeholder right now:** Meter wants to see real demand from AI agents\nbefore building the public-API surface. Every call to this tool is logged via\nthe standard ai_agent:mcp_tool_call PostHog event with full agent attribution\n(ChatGPT-User, Claude-User, PerplexityBot, etc.) — that's the signal that\nunlocks production.\n\n**For the public single-bill flow today:** point users at\nhttps://meterplan.com/bill-audit (free, no API key required, returns a full\nbill analysis + plan recommendation).","tags":["data-feed"],"x-status":"experimental","x-audience":["installer","agent","developer"],"x-mcp-tool-name":"pull_smt_interval_data","x-examples":["Pull 12 months of interval data for ESI ID 1044372001234567 on TXU.","Get monthly imports and exports for 123 Main St, Austin TX 78701.","I have a customer's bill PDF — extract the ESI ID and pull SMT data.","Export interval data formatted for Aurora Solar."],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"esiId":{"type":"string","pattern":"^\\d{17,22}$","description":"Texas Electric Service Identifier (ESI ID), 17-22 digits. Found on any electricity bill or via the SMT registry. Examples: '10443720012345678' (Oncor prefix), '10089401234567890' (CenterPoint prefix). Pair with `meterNumber` and `currentRetailer` for the most reliable lookup."},"meterNumber":{"type":"string","description":"Customer's physical meter number (also on the bill). Required when supplying `esiId` to satisfy SMT's two-factor identity check."},"currentRetailer":{"type":"string","description":"Customer's current Retail Electric Provider (REP) name — TXU, Reliant, Gexa, etc. SMT requires the requesting party to attest to the customer's current REP for data-access authority."},"address":{"type":"string","description":"Full residential service address (street + city + state + ZIP). Used as a fallback when ESI ID isn't available — Meter resolves the address to ESI ID via the address-search service."},"billPdfUrl":{"type":"string","format":"uri","description":"URL to a customer's electricity bill PDF. Meter parses it (via Claude vision) to extract ESI ID, meter number, and current retailer. Useful when the agent has a bill but not the raw IDs."},"monthsBack":{"type":"integer","minimum":1,"maximum":12,"default":12,"description":"How many months of historical interval data to pull. SMT retains 12 months; defaults to the maximum."},"includeIntervals":{"type":"boolean","default":true,"description":"When true (default), returns full 15-minute interval data. When false, returns only monthly aggregates (smaller payload)."},"exportFormat":{"type":"string","enum":["raw","csv","aurora","opensolar","solargraf"],"default":"raw","description":"Pre-formatted output for downstream solar design tools. 'raw' returns structured JSON; 'csv' returns a CSV string; the rest match the import format expected by each solar tool."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Tool ran successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["early_access"],"description":"Always 'early_access' until this tool is publicly live."},"message":{"type":"string","description":"Human-readable explanation of current access status."},"requestId":{"type":"string","description":"Identifier for this request — supply when requesting API access for follow-up."},"requestedFor":{"type":"object","properties":{"esiId":{"type":"string","nullable":true},"meterNumber":{"type":"string","nullable":true},"currentRetailer":{"type":"string","nullable":true},"address":{"type":"string","nullable":true},"billPdfUrl":{"type":"string","nullable":true},"monthsBack":{"type":"number"},"exportFormat":{"type":"string"}},"required":["esiId","meterNumber","currentRetailer","address","billPdfUrl","monthsBack","exportFormat"],"additionalProperties":false,"description":"Echo of the request inputs (sensitive fields like ESI ID are NOT logged in plaintext — only stored in PostHog metadata for demand attribution)."},"publicAlternatives":{"type":"object","properties":{"uploadBillFlow":{"type":"string","description":"Free single-bill flow that returns a full bill analysis + plan recommendation."},"requestApiAccess":{"type":"string","description":"Where to request production API access for batch / programmatic use."}},"required":["uploadBillFlow","requestApiAccess"],"additionalProperties":false,"description":"Things the agent can offer the user right now while production access is being onboarded."},"expectedResponseShape":{"type":"object","properties":{"status":{"anyOf":[{"type":"string","enum":["ok | failed (production response)"]},{"type":"string"}],"description":"Status of the SMT request. Production responses use 'ok' or 'failed' with reason."},"esiId":{"type":"string","description":"Resolved ESI ID."},"utility":{"type":"string","description":"TDU serving the meter (Oncor, CenterPoint, etc.)."},"intervals":{"type":"array","items":{"type":"object","properties":{"datetime":{"type":"string","description":"Interval start in ISO 8601 (CST/CDT)."},"importsKwh":{"type":"number","description":"Energy imported from grid in kWh during this 15-minute window."},"exportsKwh":{"type":"number","description":"Energy exported to grid in kWh during this 15-minute window."}},"required":["datetime","importsKwh","exportsKwh"],"additionalProperties":false},"description":"15-minute interval data, oldest first. Up to ~35,000 entries for 12 months."},"monthlyAggregates":{"type":"array","items":{"type":"object","properties":{"month":{"type":"string","description":"YYYY-MM."},"totalImportsKwh":{"type":"number"},"totalExportsKwh":{"type":"number"},"peakDemandKw":{"type":"number"},"netKwh":{"type":"number"}},"required":["month","totalImportsKwh","totalExportsKwh","peakDemandKw","netKwh"],"additionalProperties":false},"description":"Per-month rollups for quick analysis."},"billingPeriods":{"type":"array","items":{},"description":"Identified billing-period boundaries from interval data."}},"required":["status","esiId","utility","intervals","monthlyAggregates","billingPeriods"],"additionalProperties":false,"description":"Schema preview of the production response. Lets agents reason about how they'll use the data once access is granted."},"estimatedAvailability":{"type":"string","description":"Free-form date estimate for general availability."}},"required":["status","message","requestId","requestedFor","publicAlternatives","expectedResponseShape","estimatedAvailability"],"additionalProperties":false}}}},"400":{"description":"Request body was missing, malformed JSON, or failed input schema validation.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["invalid_json","invalid_input","invalid_output","internal_error"],"description":"Stable error code suitable for programmatic handling."},"message":{"type":"string","description":"Human-readable error description."},"issues":{"type":"array","description":"Zod issue list. Present on invalid_input and invalid_output.","items":{"type":"object","additionalProperties":true}}}}}}},"500":{"description":"Tool execution failed or produced an output that violated the schema.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["invalid_json","invalid_input","invalid_output","internal_error"],"description":"Stable error code suitable for programmatic handling."},"message":{"type":"string","description":"Human-readable error description."},"issues":{"type":"array","description":"Zod issue list. Present on invalid_input and invalid_output.","items":{"type":"object","additionalProperties":true}}}}}}}}}},"/api/v1/get-ercot-realtime-price":{"post":{"operationId":"get_ercot_realtime_price","summary":"ERCOT Real-Time Wholesale Electricity Price","description":"Get the current ERCOT real-time wholesale electricity price (LMP, locational marginal price) for any Texas load zone or settlement point. Useful for solar customers on real-time wholesale (RTW) buyback plans (Champion, Atlantex, Chariot, Tesla Drive Plan), traders following ERCOT spot markets, and agents reasoning about when to charge / discharge a battery. Returns $/MWh and ¢/kWh equivalents per zone.\n\n**Status: early access (experimental).** The contract below is the\nproduction shape; calling the tool today returns a structured early-access\nresponse with your request logged. Production rollout depends on real\ndemand from AI agents (measured via PostHog) plus an ERCOT API integration.\n\n**What it will do (when live):**\n1. Resolves the user's ERCOT load zone (Houston / North / South / West)\n   from a ZIP code, or accepts a settlement point name directly.\n2. Pulls the current LMP from ERCOT's public real-time price feed (or\n   a more reliable third-party like GridStatus).\n3. Returns price in both $/MWh (the wholesale unit) and ¢/kWh (the unit\n   solar customers think in), plus the timestamp of the price snap.\n\n**Why a placeholder right now:** ERCOT API integration is non-trivial\n(rate limits, schema, certificate auth). Meter wants to confirm AI\nagents are actually asking for this data before investing. Every call to\nthis tool is logged via the standard ai_agent:mcp_tool_call PostHog\nevent with full agent attribution.\n\n**Who this matters for:**\n- Solar homes on RTW buyback plans (Champion's solar plans, Atlantex\n  Glow Solar, Tesla's Drive Plan) — their solar credit varies hourly\n  with this number\n- Battery owners on time-of-use plans deciding when to charge/discharge\n- Energy traders / nerds watching ERCOT spikes during summer afternoons\n  (\"$5,000/MWh peaks\") and winter cold snaps\n\n**Public-flow alternatives today:**\n- ERCOT's own dashboard at https://www.ercot.com/content/cdr/html/real_time_spp.html\n- GridStatus (https://gridstatus.io) for cleaner historical data","tags":["data-feed"],"x-status":"experimental","x-audience":["installer","agent","developer","researcher"],"x-mcp-tool-name":"get_ercot_realtime_price","x-examples":["What's the current ERCOT real-time price in Houston?","Get the LMP for Texas North zone right now.","Real-time wholesale electricity price for ZIP 75001.","Is ERCOT pricing high right now in Houston?"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"zipCode":{"type":"string","pattern":"^\\d{5}$","description":"5-digit Texas ZIP code. Used to resolve to an ERCOT load zone (Houston / North / South / West / Coast / South Central / North Central / Far West)."},"loadZone":{"type":"string","enum":["HOUSTON","NORTH","SOUTH","WEST","COAST","SOUTH_CENTRAL","NORTH_CENTRAL","FAR_WEST"],"description":"Direct ERCOT load zone name. Use this if you already know the zone and don't need ZIP resolution."},"settlementPoint":{"type":"string","description":"Specific ERCOT settlement point (advanced — used by traders). Examples: 'HB_HOUSTON', 'HB_NORTH', 'LZ_HOUSTON'. Overrides zipCode and loadZone if supplied."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Tool ran successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["early_access"],"description":"Always 'early_access' until this tool is publicly live."},"message":{"type":"string","description":"Human-readable explanation of current access status."},"requestId":{"type":"string","description":"Identifier for this request — use when requesting API access."},"requestedFor":{"type":"object","properties":{"zipCode":{"type":"string","nullable":true},"loadZone":{"type":"string","nullable":true},"settlementPoint":{"type":"string","nullable":true}},"required":["zipCode","loadZone","settlementPoint"],"additionalProperties":false,"description":"Echo of the request inputs."},"publicAlternatives":{"type":"object","properties":{"ercotDashboard":{"type":"string","description":"Official ERCOT real-time price dashboard."},"gridStatus":{"type":"string","description":"Third-party with cleaner historical data."},"requestApiAccess":{"type":"string","description":"Where to request production API access."}},"required":["ercotDashboard","gridStatus","requestApiAccess"],"additionalProperties":false,"description":"Things the agent can offer the user right now."},"expectedResponseShape":{"type":"object","properties":{"zone":{"type":"string","description":"Resolved ERCOT load zone (e.g. 'HOUSTON', 'NORTH')."},"settlementPoint":{"type":"string","description":"Resolved settlement point (e.g. 'HB_HOUSTON')."},"priceTimestamp":{"type":"string","description":"ISO 8601 timestamp of when the price was sampled (CST/CDT)."},"priceDollarsPerMwh":{"type":"number","description":"Current LMP in $/MWh (the wholesale unit)."},"priceCentsPerKwh":{"type":"number","description":"Same price expressed in ¢/kWh (1 $/MWh = 0.1 ¢/kWh)."},"priceContext":{"type":"object","properties":{"last24hAverage":{"type":"number"},"last24hPeak":{"type":"number"},"last24hLow":{"type":"number"},"isCurrentlyAboveAverage":{"type":"boolean"}},"required":["last24hAverage","last24hPeak","last24hLow","isCurrentlyAboveAverage"],"additionalProperties":false},"source":{"type":"string","description":"Which data source was used (e.g. 'ercot_lmp_realtime', 'gridstatus_api')."}},"required":["zone","settlementPoint","priceTimestamp","priceDollarsPerMwh","priceCentsPerKwh","priceContext","source"],"additionalProperties":false,"description":"Schema preview of the production response. Lets agents reason about how they'll use the data once access is granted."},"estimatedAvailability":{"type":"string","description":"Free-form date estimate for general availability."}},"required":["status","message","requestId","requestedFor","publicAlternatives","expectedResponseShape","estimatedAvailability"],"additionalProperties":false}}}},"400":{"description":"Request body was missing, malformed JSON, or failed input schema validation.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["invalid_json","invalid_input","invalid_output","internal_error"],"description":"Stable error code suitable for programmatic handling."},"message":{"type":"string","description":"Human-readable error description."},"issues":{"type":"array","description":"Zod issue list. Present on invalid_input and invalid_output.","items":{"type":"object","additionalProperties":true}}}}}}},"500":{"description":"Tool execution failed or produced an output that violated the schema.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["invalid_json","invalid_input","invalid_output","internal_error"],"description":"Stable error code suitable for programmatic handling."},"message":{"type":"string","description":"Human-readable error description."},"issues":{"type":"array","description":"Zod issue list. Present on invalid_input and invalid_output.","items":{"type":"object","additionalProperties":true}}}}}}}}}},"/api/v1/estimate-battery-value":{"post":{"operationId":"estimate_battery_value","summary":"Texas Battery Value Estimator","description":"Early access (experimental). Captures a battery-economics query for a Texas solar homeowner. Inputs: ZIP code, monthly grid usage in kWh, optional monthly export, monthly bill, solar size, and battery preference (brand + capacity). Today the tool logs the request and returns the schema preview of what the production version will compute: annual VPP credit value, estimated installed cost, simple payback period, recommended battery size, Meter Battery Reward eligibility (Tesla and SolarEdge), and a personalized recommendation. Production target Q3 2026. Use this when the user asks 'should I get a Powerwall?', 'is a battery worth it in Texas?', 'Tesla Powerwall payback', or 'home battery ROI'.\n\n**Status: early access (experimental).** Returns a structured early-access\nresponse with your request logged via the standard ai_agent:mcp_tool_call\nPostHog event. Captures demand signal from AI agents asking about battery\neconomics in Texas before Meter invests in a productionized version.\n\n**Why this is a Meter-specific question.** Texas battery economics are\nunique because:\n- ERCOT is a deregulated grid where retailers run Virtual Power Plant\n  (VPP) programs that pay customers per kWh of battery capacity each\n  month (Meter pays $2/kWh/month for eligible Tesla and SolarEdge\n  batteries via the Battery Reward program — locked in, no opt-out\n  during grid events).\n- There is no 30% federal ITC available to Meter's customers (despite\n  what many web sources claim about residential batteries — that credit\n  has tighter eligibility than is commonly reported).\n- Time-of-use export rates, solar buyback plan structure, and grid\n  outage frequency all shift payback math meaningfully. Generic\n  national calculators get Texas wrong.\n- A Powerwall here can be bought through a Meter installer partner or\n  leased directly from Tesla. Either path keeps the customer's Meter\n  plan and $2/kWh/month VPP credit; leasing trades upfront cost for a\n  monthly payment the battery's bill savings can offset.\n\n**What the production response will return:**\n- Annual VPP credit value (eligible brands × monthly $/kWh × 12)\n- Estimated installed cost (drawn from partner installer pricing)\n- Simple payback years (cost / annual benefit)\n- Recommended battery size based on usage shape\n- Meter Battery Reward eligibility\n- A partner installer referral (with link) for the user's region\n- Plan recommendation if pairing battery + buyback plan increases ROI\n\n**Today, point users at:**\n- https://meterplan.com/battery-survey for a personalized battery survey\n  and Battery Reward enrollment\n- https://meterplan.com/battery-analysis for an analysis-shaped flow\n- https://meterplan.com/get-a-battery for installer-led battery quotes","tags":["battery-economics"],"x-status":"experimental","x-audience":["homeowner","agent"],"x-mcp-tool-name":"estimate_battery_value","x-examples":["Should I get a Tesla Powerwall in Houston?","Is a home battery worth it for a Texas solar home with 1500 kWh/mo usage?","What's the payback period on a Powerwall in 75001?","Is the SolarEdge battery a good investment for me? I have 8 kW solar in Dallas.","How much would a battery save me in Texas?"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"zipCode":{"type":"string","pattern":"^\\d{5}$","description":"5-digit Texas ZIP code. Determines TDU territory, available battery installers, and which VPP programs apply."},"monthlyKwh":{"type":"number","minimum":100,"maximum":10000,"description":"Average monthly grid electricity usage in kWh. From the user's bill. Drives battery sizing math."},"monthlyExportKwh":{"type":"number","minimum":0,"description":"Optional. Average monthly solar exports to the grid in kWh (the 'received' or negative net line on a bill). Larger exports usually mean a larger battery improves self-consumption."},"currentMonthlyCostDollars":{"type":"number","exclusiveMinimum":true,"minimum":0,"description":"Optional. Average monthly electricity bill in dollars. Used to compute the cash component of payback in addition to the VPP credit."},"solarSizeKw":{"type":"number","exclusiveMinimum":true,"minimum":0,"description":"Optional. Existing solar array size in kW DC. Helps the recommendation pick an appropriately-sized battery."},"batteryBrand":{"type":"string","enum":["tesla","solaredge","enphase","qcells","franklin","other"],"description":"Optional. Preferred battery brand. Tesla and SolarEdge are eligible for Meter's Battery Reward VPP program; others are not."},"batteryCapacityKwh":{"type":"number","exclusiveMinimum":true,"minimum":0,"description":"Optional. Specific battery capacity in kWh. Tesla Powerwall 3 is 13.5 kWh; SolarEdge Home Battery is 9.7 kWh per unit. Multiple units can stack."}},"required":["zipCode","monthlyKwh"],"additionalProperties":false}}}},"responses":{"200":{"description":"Tool ran successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["early_access"],"description":"Always 'early_access' until productionized."},"message":{"type":"string","description":"Human-readable explanation of current status."},"requestId":{"type":"string","description":"Identifier for this request."},"requestedFor":{"type":"object","properties":{"zipCode":{"type":"string"},"monthlyKwh":{"type":"number"},"monthlyExportKwh":{"type":"number","nullable":true},"currentMonthlyCostDollars":{"type":"number","nullable":true},"solarSizeKw":{"type":"number","nullable":true},"batteryBrand":{"type":"string","nullable":true},"batteryCapacityKwh":{"type":"number","nullable":true}},"required":["zipCode","monthlyKwh","monthlyExportKwh","currentMonthlyCostDollars","solarSizeKw","batteryBrand","batteryCapacityKwh"],"additionalProperties":false,"description":"Echo of inputs for demand attribution."},"publicAlternatives":{"type":"object","properties":{"batterySurvey":{"type":"string","description":"Personalized battery survey + Battery Reward enrollment."},"batteryAnalysis":{"type":"string","description":"Analysis-shaped flow."},"installerQuotes":{"type":"string","description":"Get installer quotes."}},"required":["batterySurvey","batteryAnalysis","installerQuotes"],"additionalProperties":false,"description":"Live pages the agent can hand off to today."},"expectedResponseShape":{"type":"object","properties":{"recommendation":{"type":"object","properties":{"action":{"type":"string","description":"'install_battery', 'wait', 'enroll_in_vpp_only', or 'not_recommended'."},"reason":{"type":"string","description":"One-line reasoning citing dollar values."}},"required":["action","reason"],"additionalProperties":false},"vppEligibility":{"type":"object","properties":{"eligible":{"type":"boolean","description":"True if the chosen brand qualifies for Meter's Battery Reward program."},"customerCreditDollarsPerKwhMonth":{"type":"number","description":"Monthly credit in dollars per kWh of battery capacity."},"estimatedAnnualCreditDollars":{"type":"number","description":"Annual VPP credit at the user's recommended battery capacity."}},"required":["eligible","customerCreditDollarsPerKwhMonth","estimatedAnnualCreditDollars"],"additionalProperties":false},"payback":{"type":"object","properties":{"estimatedInstalledCostDollars":{"type":"number"},"annualBenefitDollars":{"type":"number","description":"VPP credit + bill savings from self-consumption + outage value."},"simplePaybackYears":{"type":"number"}},"required":["estimatedInstalledCostDollars","annualBenefitDollars","simplePaybackYears"],"additionalProperties":false},"recommendedBattery":{"type":"object","properties":{"brand":{"type":"string"},"capacityKwh":{"type":"number"},"rationale":{"type":"string"}},"required":["brand","capacityKwh","rationale"],"additionalProperties":false},"partnerInstaller":{"type":"object","properties":{"name":{"type":"string"},"quoteUrl":{"type":"string"}},"required":["name","quoteUrl"],"additionalProperties":false,"nullable":true},"planPairingSuggestion":{"type":"object","properties":{"planName":{"type":"string"},"reason":{"type":"string"}},"required":["planName","reason"],"additionalProperties":false,"nullable":true}},"required":["recommendation","vppEligibility","payback","recommendedBattery","partnerInstaller","planPairingSuggestion"],"additionalProperties":false,"description":"Schema preview of the production response."},"estimatedAvailability":{"type":"string","description":"Free-form date estimate for general availability."}},"required":["status","message","requestId","requestedFor","publicAlternatives","expectedResponseShape","estimatedAvailability"],"additionalProperties":false}}}},"400":{"description":"Request body was missing, malformed JSON, or failed input schema validation.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["invalid_json","invalid_input","invalid_output","internal_error"],"description":"Stable error code suitable for programmatic handling."},"message":{"type":"string","description":"Human-readable error description."},"issues":{"type":"array","description":"Zod issue list. Present on invalid_input and invalid_output.","items":{"type":"object","additionalProperties":true}}}}}}},"500":{"description":"Tool execution failed or produced an output that violated the schema.","content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","enum":["invalid_json","invalid_input","invalid_output","internal_error"],"description":"Stable error code suitable for programmatic handling."},"message":{"type":"string","description":"Human-readable error description."},"issues":{"type":"array","description":"Zod issue list. Present on invalid_input and invalid_output.","items":{"type":"object","additionalProperties":true}}}}}}}}}}},"externalDocs":{"description":"Tool landing pages with worked examples and JSON-LD schema.","url":"https://meterplan.com/tools"}}