Skip to main content
Glama

Ephemeris Time-Series Forecasting

by industries.cascade
OverviewDiscussionsAdmin

Forecast a time series

forecast

Submit numeric observations to forecast future sampling steps. Spends credits on successful calls. Choose and retain idempotency_key before submitting; no automatic retries, replay depends on server retention. Minimal example: {mode: route, series: [{values: [10,12,11], freq: D}], horizon: 2, quantiles: [0.1,0.5,0.9]}. Returns forecasts and meta as before, plus artifact by default for describe_forecast/plot_forecast. Save the embedded JSON attachment: it includes full input history and local context; no hosted storage is created. Context never becomes a model input. Billing is at meta.billing in millicredit strings (100 mc = 0.1 credits). Missing future inputs mean not supplied, not no events. Quantile bands do not establish coverage, cumulative intervals or peak probabilities. After uncertain completion, reuse the same key and API request; an expired key may cause a new charge.

Input Schema

NameRequiredDescriptionDefault
modeYes"route": automatically select a model. "ensemble": blend compatible models and may cost more. Neither guarantees accuracy or calibration. "explicit": run the single model named in `model`.
modelNoRequired when mode is "explicit". Must be a name returned by list_models.
top_kNoEnsemble only: cap on how many models participate.
seriesYesOne to 64 series forecast in one request. All share horizon and quantiles.
combineNoEnsemble only. "mixture" averages the predictive distributions (default); "vincentize" averages the quantiles.
contextNoLocal artifact metadata, never sent as model inputs. series aligns with input series; timestamps align with history and future_timestamps with horizon. Units/target/measurement/timezone must come from the user; unknowns stay null. Future-input labels are caller assertions; narrative assumptions do not change inference.
horizonNoNumber of future steps to forecast, 1 to 4096. Defaults to 64. Some models stop short of this (max_horizon in list_models): route and ensemble skip them, explicit mode rejects the request.
quantilesNoUp to 21 quantile levels strictly between 0 and 1, for example [0.1, 0.5, 0.9]. The response keys forecasts by these as decimal strings.
context_lenNoMost recent points per variate to feed the model (history length does not affect pricing), 1 to 16384. Defaults to 256. Values beyond the model's context cap are truncated at the cap.
idempotency_keyNoClient-chosen key, 8 to 128 characters of letters, numbers, dot, underscore, colon or hyphen. A retry with the same key and identical API body replays while retained by the server. Retain the key before submission; expired keys may cause a new charge.
include_artifactNoDefault true: include a portable ephemeris.forecast v1 artifact and embedded JSON attachment (up to 1 MiB), with full input history. Save it client-side for describe_forecast/plot_forecast or the CLI. false returns the existing API response only. No persistent hosted storage is created.

Output Schema

NameRequiredDescriptionDefault
metaNo
artifactNoPortable ephemeris.forecast v1 JSON including full history and local context. Save client-side and pass the object to describe_forecast/plot_forecast. Not a hosted URL.
forecastsNoOne entry per input series, aligned with the request.
artifact_errorNo
artifact_statusNoincluded or unavailable. A packaging/size failure never discards the paid forecasts/meta response.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / context_len / description
      Previous value: -"Most recent points per variate to feed the model and bill for, 1 to 16384. Defaults to 256. Values beyond the model's context cap are truncated at the cap."New value: +"Most recent points per variate to feed the model (history length does not affect pricing), 1 to 16384. Defaults to 256. Values beyond the model's context cap are truncated at the cap."
  2. Changed8 schema fields changed
    • addedInput schema / properties / context
      Added value: +{
+  "additionalProperties": false,
+  "description": "Local artifact metadata, never sent as model inputs. series aligns with input series; timestamps align with history and future_timestamps with horizon. Units/target/measurement/timezone must come from the user; unknowns stay null. Future-input labels are caller assertions; narrative assumptions do not change inference.",
+  "properties": {
+    "scenario_assumptions": {
+      "items": {
+        "maxLength": 2000,
+        "type": "string"
+      },
+      "maxItems": 100,
+      "type": "array"
+    },
+    "series": {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "future_covariate_roles": {
+            "additionalProperties": {
+              "enum": [
+                "known_future",
+                "scenario_assumption",
+                "unspecified"
+              ],
+              "type": "string"
+            },
+            "propertyNames": {
+              "type": "string"
+            },
+            "type": "object"
+          },
+          "future_timestamps": {
+            "anyOf": [
+              {
+                "items": {
+                  "maxLength": 100,
+                  "type": "string"
+                },
+                "type": "array"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "measurement": {
+            "anyOf": [
+              {
+                "enum": [
+                  "period_total",
+                  "period_average",
+                  "point_in_time"
+                ],
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "recorded_as_of": {
+            "anyOf": [
+              {
+                "maxLength": 2000,
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "series_id": {
+            "anyOf": [
+              {
+                "maxLength": 2000,
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "source_available_at": {
+            "anyOf": [
+              {
+                "maxLength": 2000,
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "target_description": {
+            "anyOf": [
+              {
+                "maxLength": 2000,
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "timestamps": {
+            "anyOf": [
+              {
+                "items": {
+                  "maxLength": 100,
+                  "type": "string"
+                },
+                "type": "array"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "timezone": {
+            "anyOf": [
+              {
+                "maxLength": 2000,
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "unit": {
+            "anyOf": [
+              {
+                "maxLength": 2000,
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          }
+        },
+        "type": "object"
+      },
+      "maxItems": 64,
+      "type": "array"
+    }
+  },
+  "required": [
+    "series"
+  ],
+  "type": "object"
+}
    • changedInput schema / properties / idempotency_key / description
      Previous value: -"Client-chosen key, 8 to 128 characters of letters, numbers, dot, underscore, colon or hyphen. A retry with the same key and identical body replays the stored result without charging again."New value: +"Client-chosen key, 8 to 128 characters of letters, numbers, dot, underscore, colon or hyphen. A retry with the same key and identical API body replays while retained by the server. Retain the key before submission; expired keys may cause a new charge."
    • addedInput schema / properties / include_artifact
      Added value: +{
+  "description": "Default true: include a portable ephemeris.forecast v1 artifact and embedded JSON attachment (up to 1 MiB), with full input history. Save it client-side for describe_forecast/plot_forecast or the CLI. false returns the existing API response only. No persistent hosted storage is created.",
+  "type": "boolean"
+}
    • changedInput schema / properties / mode / description
      Previous value: -"\"route\": Ephemeris picks the best model for the data, falling back to a small ensemble if it fails. \"ensemble\": run all compatible models and blend them; best calibration, highest cost. \"explicit\": run the single model named in `model`."New value: +"\"route\": automatically select a model. \"ensemble\": blend compatible models and may cost more. Neither guarantees accuracy or calibration. \"explicit\": run the single model named in `model`."
    • changedInput schema / properties / series / items / properties / covariates / properties / future / description
      Previous value: -"Known-future channels, each exactly `horizon` long. Every future channel must also appear in `past`."New value: +"Future numeric channels (known future or explicit scenario assumptions), each exactly `horizon` long. Every future channel must also appear in `past`."
    • addedOutput schema / properties / artifact
      Added value: +{
+  "additionalProperties": {},
+  "description": "Portable ephemeris.forecast v1 JSON including full history and local context. Save client-side and pass the object to describe_forecast/plot_forecast. Not a hosted URL.",
+  "propertyNames": {
+    "type": "string"
+  },
+  "type": "object"
+}
    • addedOutput schema / properties / artifact_error
      Added value: +{
+  "type": "string"
+}
    • addedOutput schema / properties / artifact_status
      Added value: +{
+  "description": "included or unavailable. A packaging/size failure never discards the paid forecasts/meta response.",
+  "type": "string"
+}
  3. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Substantially exceeds the annotations: it discloses credit spend on successful calls, replay/retention semantics, that no hosted storage is created, that context never becomes a model input, billing units (millicredits), and interpretive caveats about missing future inputs and quantile bands. This is exactly the kind of behavior annotations cannot convey.

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

Conciseness4/5

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

Front-loaded with purpose and the minimal example, then organized around operational warnings. Dense but each sentence carries actionable content, though a few points (idempotency retention) echo the schema descriptions.

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 11 parameters, an output schema, and rich annotations, the description still covers the non-obvious operational and interpretive dimensions (billing, idempotency, artifact handling, output interpretation) that an agent needs before invoking this costly, open-world tool.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine semantic interpretation beyond the schema — missing future inputs mean 'not supplied' rather than 'no events,' quantile bands do not establish coverage/peak probabilities, and idempotency/artifact behavior is restated with operational framing.

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?

States a specific verb and resource: 'Submit numeric observations to forecast future sampling steps.' It also implicitly distinguishes itself from describe_forecast/plot_forecast, which are positioned as consumers of the artifact produced here.

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

Usage Guidelines4/5

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

Gives strong operational guidance (retain idempotency_key before submitting, reuse the same key and request after uncertain completion, no automatic retries) and clarifies how the artifact feeds describe_forecast/plot_forecast. However it does not explicitly frame when to prefer forecast over list_models or the other siblings beyond artifact consumption.

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

All Ephemeris Time-Series Forecasting toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources