# tou.tools

tou.tools provides a Time-of-Use (TOU) electricity schedule API. It resolves any U.S. address or ZIP code to its electric utility and returns the current active period (e.g., on-peak, off-peak) and schedule. Available via REST API and as a native MCP server for AI agents.

## TL;DR
- **What it is**: An API and MCP server for real-time U.S. TOU electricity schedules.
- **What it does**: Returns period names (on-peak, off-peak, etc.) and boundaries based on location.
- **What it does not do**: It does not return ¢/kWh prices.
- **Who it is for**: Solo devs, smart home builders, AI agents, EV charging operators, commercial energy managers.

## Scope
The scope is deliberately narrow: period names, boundaries, and schedules only. tou.tools does not return ¢/kWh prices — those vary by tariff rider, customer class, and baseline allowance, and are out of scope. What you get is the timing layer: which period is active, and exactly when it changes.

## Integration Methods
1. **REST API**: plain HTTP GET requests returning JSON.
2. **MCP server**: a Model Context Protocol endpoint that AI agents can call as a native tool, with no integration code.

## REST API Documentation

### Base URL
`https://tou.tools/api/v1`

### Authentication
Requests authenticate with an API key passed as a bearer token in the `Authorization` header. Keys are prefixed `tou_`.
Example: `Authorization: Bearer tou_xxxxxxxxxxxxxxxxxxxxxxxxxxxx`

### Current Period
`GET /api/v1/query/current`

Parameters:
- `zip_code` (required): 5-digit U.S. ZIP code.
- `customer_class` (optional): `residential` (default), `commercial`, `industrial`, `agricultural`, `ev`.
- `at` (optional): ISO 8601 timestamp with timezone offset.
- `street`, `city`, `state` (optional): For address-level disambiguation.

### Full Schedule
`GET /api/v1/query/schedule`

Parameters:
- `rate_plan_id` (required): The rate plan's UUID.

### Coverage
`GET /api/v1/coverage`
Lists every utility with at least one active rate plan, the states it serves, and which customer classes are covered. Public — no key required.

## MCP Integration

tou.tools ships as an MCP server. The server speaks streamable HTTP at `https://tou.tools/mcp`.
Connect with an `Authorization: Bearer tou_…` header — the same API key you use for REST.

### Available MCP Tools
- `get_current_period`: Takes a `zip_code`. Returns the current period and next-change time for each active residential rate plan serving the ZIP.
- `get_schedule`: Takes a `rate_plan_id`. Returns the full schedule — all periods, ranges, and seasons.
- `list_utilities`: Takes a `state` (2-letter abbreviation). Returns utilities with TOU rate plans in that state.

## TOU Periods
- `off_peak`: Lowest-demand window, and the implicit default.
- `mid_peak`: Shoulder period between off-peak and on-peak.
- `on_peak`: Highest-demand window.
- `super_off_peak`: Deepest discount window.
- `critical_peak`: Event-based critical-peak window.

## Pricing
- Free: $0, 3 locations, 250 calls/mo
- Builder: $49, 75 locations, 25,000 calls/mo
- Growth: $179, 300 locations, 150,000 calls/mo
- Business: $449, 1,500 locations, 750,000 calls/mo
- Enterprise: custom, unlimited