{"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."}],"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."}},"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 inlined as a data URI (base64). Null if no logo is on file. Inlined because the ChatGPT iframe CSP `img-src` policy permits only 'self' and data URIs."},"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":"Up to 6 electricity plans available at the ZIP, ranked by effective rate ascending (cheapest first). Includes 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/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}}}}}}}}}}},"externalDocs":{"description":"Tool landing pages with worked examples and JSON-LD schema.","url":"https://meterplan.com/tools"}}