aeso-mcp

Overview Schema Source Related Servers Discussions Admin

Compare Forecast To Actual

compare_forecast_to_actual

Read-onlyIdempotent

Compare Alberta Internal Load forecast against actual values for a chosen time range, returning mean error, MAE, RMSE, MAPE, and paired intervals to quantify forecast accuracy.

Instructions

Compares Alberta Internal Load forecast versus actual over [start, end) in MW. Returns mean error, MAE, RMSE, MAPE, and paired intervals. Timestamps are America/Edmonton.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`request`	Yes	Compare Alberta Internal Load forecast versus actual over a range.

Output Schema

TableJSON Schema

Name	Required	Description
`rmse_mw`	No
`metadata`	Yes	Provenance and semantic metadata attached to dataset responses.
`warnings`	No
`intervals`	No	Paired intervals (may be truncated for large ranges).
`mean_error_mw`	No
`max_abs_error_mw`	No
`mean_abs_error_mw`	No
`observation_count`	Yes
`mean_abs_pct_error`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.3.0Aug 28, 2026

changedOutput schema / properties / metadata / properties / provider / enum

Previous value: -[
-  "gridstatus",
-  "aeso_apim",
-  "aeso_public_report",
-  "derived"
-]New value: +[
+  "gridstatus",
+  "aeso_apim",
+  "aeso_public_report",
+  "aeso_csd_archive",
+  "derived"
+]

Changed13 schema fields changedv0.2.0Aug 24, 2026

addedOutput schema / properties / metadata / properties / available_series

Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedOutput schema / properties / metadata / properties / cache_age

Added value: +{
+  "anyOf": [
+    {
+      "type": "number"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Age of the cached provider result in seconds when served."
+}

addedOutput schema / properties / metadata / properties / cache_hit
```
Added value: +{
+  "default": false,
+  "type": "boolean"
+}
```

addedOutput schema / properties / metadata / properties / completeness

Added value: +{
+  "default": "unknown",
+  "description": "Completeness of the requested observations or series.",
+  "enum": [
+    "complete",
+    "partial",
+    "degraded",
+    "empty",
+    "unknown"
+  ],
+  "type": "string"
+}

addedOutput schema / properties / metadata / properties / expected_observation_count

Added value: +{
+  "anyOf": [
+    {
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null
+}

addedOutput schema / properties / metadata / properties / expected_observations

Added value: +{
+  "anyOf": [
+    {
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null
+}

addedOutput schema / properties / metadata / properties / finality

Added value: +{
+  "default": "unknown",
+  "description": "Whether published observations are final or still preliminary.",
+  "enum": [
+    "final",
+    "preliminary",
+    "unknown"
+  ],
+  "type": "string"
+}

addedOutput schema / properties / metadata / properties / missing_observation_count

Added value: +{
+  "anyOf": [
+    {
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null
+}

addedOutput schema / properties / metadata / properties / missing_observations

Added value: +{
+  "anyOf": [
+    {
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null
+}

addedOutput schema / properties / metadata / properties / missing_series

Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedOutput schema / properties / metadata / properties / observation_type

Added value: +{
+  "default": "actual",
+  "description": "What kind of observation a response contains.\n\n``DataStatus`` predates this distinction and remains available for\ncompatibility.  ``observation_type`` should be used when a client needs\nto distinguish an actual observation from a forecast or a derived value.",
+  "enum": [
+    "actual",
+    "forecast",
+    "derived",
+    "unknown"
+  ],
+  "type": "string"
+}

changedOutput schema / properties / metadata / properties / provider / enum

Previous value: -[
-  "gridstatus",
-  "aeso_apim",
-  "derived"
-]New value: +[
+  "gridstatus",
+  "aeso_apim",
+  "aeso_public_report",
+  "derived"
+]

addedOutput schema / properties / metadata / properties / served_at

Added value: +{
+  "anyOf": [
+    {
+      "format": "date-time",
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null
+}

First observedv0.1.1Aug 8, 2026

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already establish read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral context beyond annotations by clarifying half-open interval boundaries ([start, end)) and the timezone interpretation (America/Edmonton), which materially affect how inputs are interpreted and results are produced.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two efficient sentences front-load the core function, then list outputs and timezone context. Every clause adds value and nothing is redundant or speculative.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simple structure, complete parameter schemas, rich annotations, and existing output schema, the description provides sufficient context. It covers what data is compared, the interval, the units, the returned metrics, and the timezone behavior—no critical gaps remain.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, with start/end inclusivity and timezone handling already documented in the schema. The description's interval notation and timezone note largely restate this information, adding only minimal extra meaning such as the MW unit context for the comparison.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Compares'), the exact resource ('Alberta Internal Load forecast versus actual'), the interval semantics, units, and the expected outputs. This clearly differentiates the tool from siblings like get_forecast or get_load, and its metric-focused output distinguishes it from analyze_forecast_error.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the use case: when you need forecast-versus-actual error metrics over a time range. However, it does not explicitly name alternatives or state when not to use this tool, especially given closely related siblings like analyze_forecast_error and compare_market_periods.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server