Skip to main content
Glama

groundhog.markets

As-issued history

history
Read-onlyIdempotent

As-issued history for backtests (no look-ahead): kind=daily (every source's daily hi/lo/rain per run at a place), nbm (NBM text columns: TXN, XND, P12, Q12; view=day = the books' day view), obs (settlement truth: CLI, routine-METAR max/min) or markets (what the markets tool served, each change; asof = as it stood then). from/to (<= 366 days, 1 unit per 31 days); run=ISO | lead=N (+cycle=H: the run issued N days before) | asof=ISO (what was known then). Rows carry fetched_at and origin (bf:* = backfilled). TSV by default. format=json also returns structuredContent; the JSON Schema is at https://groundhog.markets/api/v1/schema.json

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "from": "<from>"
    },
    "name": "history"
  }
}

Input Schema

NameRequiredDescriptionDefault
toNolast target date (default from)
elsNokind=nbm: elements, comma list (TXN,XND,P12,Q12,TMP)
runNoone run, YYYY-MM-DDTHH:MMZ
stnNoICAO (kind=nbm, obs)
asofNonewest run fetched by this UTC time (no look-ahead); markets: each row as it stood then
fromYesfirst target date YYYY-MM-DD
kindNodaily (default) | nbm | obs | markets
leadNothe run issued N UTC days before each date
prodNokind=nbm: nbe (default) | nbs
viewNokind=nbm: raw (default) | day
cycleNowith lead: only runs at H UTC
placeNoslug, name or ICAO (kind=daily, markets; nbm/obs: its station)
fieldsNofull (default) | compact: leave out null JSON keys (format=json)
formatNotsv (default) | json
sourceNokind=daily: source ids, comma list (e.g. nbm,gfs,ifs)
compactNotrue = fields=compact
productNokind=obs

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changed
    • addedInput schema / properties / compact
      Added value: +{
      +  "description": "true = fields=compact",
      +  "type": "boolean"
      +}
    • changedInput schema / properties / fields / description
      Previous value: -"full (default) | compact: leave out null members of the JSON (structuredContent and format=json)"New value: +"full (default) | compact: leave out null JSON keys (format=json)"
    • changedOutput schema / (root)
      Previous value: -{
      -  "additionalProperties": false,
      -  "properties": {
      -    "asof": {
      -      "description": "Request time (UTC).",
      -      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}Z$",
      -      "type": "string"
      -    },
      -    "build": {
      -      "description": "The running commit, 7 hex (dev off Tokay). With method, ties this body's numbers to the code and rules that made them (CONTRACTS §51).",
      -      "type": "string"
      -    },
      -    "columns": {
      -      "description": "Row keys in TSV order.",
      -      "items": {
      -        "type": "string"
      -      },
      -      "type": "array"
      -    },
      -    "credit_keys": {
      -      "description": "Their keys (/credits lists every line).",
      -      "items": {
      -        "type": "string"
      -      },
      -      "type": "array"
      -    },
      -    "credits": {
      -      "description": "Credit strings to keep when you repeat numbers.",
      -      "items": {
      -        "type": "string"
      -      },
      -      "type": "array"
      -    },
      -    "credits_url": {
      -      "description": "The full credits page.",
      -      "type": "string"
      -    },
      -    "from": {
      -      "description": "First target date.",
      -      "type": "string"
      -    },
      -    "kind": {
      -      "const": "history",
      -      "description": "Body kind."
      -    },
      -    "method": {
      -      "description": "Method id: the contract rules that made this body's numbers (blend-median-v1, rain-month-v5, markets-nbm-led-v4, receipts-qa-v1, history-as-issued-v3, status-readiness-v1). A rule change gives a new id, so equal ids mean the same method (CONTRACTS §51).",
      -      "type": "string"
      -    },
      -    "n_rows": {
      -      "description": "Rows.",
      -      "type": "integer"
      -    },
      -    "notes": {
      -      "description": "Notes.",
      -      "items": {
      -        "type": "string"
      -      },
      -      "type": "array"
      -    },
      -    "place": {
      -      "anyOf": [
      -        {
      -          "additionalProperties": false,
      -          "properties": {
      -            "cc": {
      -              "description": "Country code.",
      -              "type": "string"
      -            },
      -            "display": {
      -              "description": "Display name.",
      -              "type": "string"
      -            },
      -            "slug": {
      -              "description": "Place slug.",
      -              "type": "string"
      -            },
      -            "stn": {
      -              "description": "Primary station (ICAO).",
      -              "type": [
      -                "string",
      -                "null"
      -              ]
      -            },
      -            "tier": {
      -              "description": "core | demand | settle.",
      -              "type": "string"
      -            },
      -            "tz": {
      -              "description": "IANA time zone.",
      -              "type": "string"
      -            }
      -          },
      -          "required": [
      -            "slug",
      -            "display",
      -            "tz",
      -            "cc",
      -            "tier"
      -          ],
      -          "type": "object"
      -        },
      -        {
      -          "type": "null"
      -        }
      -      ],
      -      "description": "The place (kind=daily, markets, or a place given for nbm/obs)."
      -    },
      -    "prod": {
      -      "description": "nbm: nbe | nbs.",
      -      "type": [
      -        "string",
      -        "null"
      -      ]
      -    },
      -    "product": {
      -      "description": "obs: CLI | METAR_R | ASOS.",
      -      "type": [
      -        "string",
      -        "null"
      -      ]
      -    },
      -    "rows": {
      -      "description": "As-issued rows; every row has origin (live | bf:<tool>) and, for runs, fetched_at; markets rows have served_at (the markets run that first served the values) and build (the deployed commit).",
      -      "items": {
      -        "additionalProperties": true,
      -        "required": [
      -          "origin"
      -        ],
      -        "type": "object"
      -      },
      -      "type": "array"
      -    },
      -    "select": {
      -      "anyOf": [
      -        {
      -          "additionalProperties": false,
      -          "properties": {
      -            "asof": {
      -              "type": [
      -                "string",
      -                "null"
      -              ]
      -            },
      -            "cycle": {
      -              "type": [
      -                "integer",
      -                "null"
      -              ]
      -            },
      -            "date": {
      -              "type": [
      -                "string",
      -                "null"
      -              ]
      -            },
      -            "lead": {
      -              "type": [
      -                "integer",
      -                "null"
      -              ]
      -            },
      -            "run": {
      -              "type": [
      -                "string",
      -                "null"
      -              ]
      -            }
      -          },
      -          "type": "object"
      -        },
      -        {
      -          "type": "null"
      -        }
      -      ],
      -      "description": "The selection asked for (run, lead, cycle; history: asof; nbm: date)."
      -    },
      -    "stn": {
      -      "description": "Station (nbm, obs).",
      -      "type": [
      -        "string",
      -        "null"
      -      ]
      -    },
      -    "table": {
      -      "description": "History table (markets: what /api/v1/markets served, one row per change, CONTRACTS §43).",
      -      "enum": [
      -        "daily",
      -        "nbm",
      -        "obs",
      -        "markets"
      -      ]
      -    },
      -    "to": {
      -      "description": "Last target date.",
      -      "type": "string"
      -    },
      -    "units": {
      -      "description": "Units of the columns.",
      -      "type": "string"
      -    },
      -    "url": {
      -      "description": "The place page.",
      -      "type": [
      -        "string",
      -        "null"
      -      ]
      -    },
      -    "v": {
      -      "const": 1,
      -      "description": "Body version."
      -    },
      -    "view": {
      -      "description": "nbm: raw | day.",
      -      "type": [
      -        "string",
      -        "null"
      -      ]
      -    }
      -  },
      -  "required": [
      -    "v",
      -    "kind",
      -    "table",
      -    "asof",
      -    "from",
      -    "to",
      -    "n_rows",
      -    "columns",
      -    "rows",
      -    "units",
      -    "notes",
      -    "credits",
      -    "credit_keys",
      -    "credits_url"
      -  ],
      -  "type": "object"
      -}New value: +null
  2. Changed1 schema field changed
    • changedOutput schema / properties / method / description
      Previous value: -"Method id: the contract rules that made this body's numbers (blend-median-v1, rain-month-v3, markets-nbm-led-v2, receipts-qa-v1, history-as-issued-v3, status-readiness-v1). A rule change gives a new id, so equal ids mean the same method (CONTRACTS §51)."New value: +"Method id: the contract rules that made this body's numbers (blend-median-v1, rain-month-v5, markets-nbm-led-v4, receipts-qa-v1, history-as-issued-v3, status-readiness-v1). A rule change gives a new id, so equal ids mean the same method (CONTRACTS §51)."
  3. Changed2 schema fields changed
    • addedInput schema / properties / fields
      Added value: +{
      +  "description": "full (default) | compact: leave out null members of the JSON (structuredContent and format=json)",
      +  "enum": [
      +    "full",
      +    "compact"
      +  ],
      +  "type": "string"
      +}
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "additionalProperties": false,
      +  "properties": {
      +    "asof": {
      +      "description": "Request time (UTC).",
      +      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}Z$",
      +      "type": "string"
      +    },
      +    "build": {
      +      "description": "The running commit, 7 hex (dev off Tokay). With method, ties this body's numbers to the code and rules that made them (CONTRACTS §51).",
      +      "type": "string"
      +    },
      +    "columns": {
      +      "description": "Row keys in TSV order.",
      +      "items": {
      +        "type": "string"
      +      },
      +      "type": "array"
      +    },
      +    "credit_keys": {
      +      "description": "Their keys (/credits lists every line).",
      +      "items": {
      +        "type": "string"
      +      },
      +      "type": "array"
      +    },
      +    "credits": {
      +      "description": "Credit strings to keep when you repeat numbers.",
      +      "items": {
      +        "type": "string"
      +      },
      +      "type": "array"
      +    },
      +    "credits_url": {
      +      "description": "The full credits page.",
      +      "type": "string"
      +    },
      +    "from": {
      +      "description": "First target date.",
      +      "type": "string"
      +    },
      +    "kind": {
      +      "const": "history",
      +      "description": "Body kind."
      +    },
      +    "method": {
      +      "description": "Method id: the contract rules that made this body's numbers (blend-median-v1, rain-month-v3, markets-nbm-led-v2, receipts-qa-v1, history-as-issued-v3, status-readiness-v1). A rule change gives a new id, so equal ids mean the same method (CONTRACTS §51).",
      +      "type": "string"
      +    },
      +    "n_rows": {
      +      "description": "Rows.",
      +      "type": "integer"
      +    },
      +    "notes": {
      +      "description": "Notes.",
      +      "items": {
      +        "type": "string"
      +      },
      +      "type": "array"
      +    },
      +    "place": {
      +      "anyOf": [
      +        {
      +          "additionalProperties": false,
      +          "properties": {
      +            "cc": {
      +              "description": "Country code.",
      +              "type": "string"
      +            },
      +            "display": {
      +              "description": "Display name.",
      +              "type": "string"
      +            },
      +            "slug": {
      +              "description": "Place slug.",
      +              "type": "string"
      +            },
      +            "stn": {
      +              "description": "Primary station (ICAO).",
      +              "type": [
      +                "string",
      +                "null"
      +              ]
      +            },
      +            "tier": {
      +              "description": "core | demand | settle.",
      +              "type": "string"
      +            },
      +            "tz": {
      +              "description": "IANA time zone.",
      +              "type": "string"
      +            }
      +          },
      +          "required": [
      +            "slug",
      +            "display",
      +            "tz",
      +            "cc",
      +            "tier"
      +          ],
      +          "type": "object"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ],
      +      "description": "The place (kind=daily, markets, or a place given for nbm/obs)."
      +    },
      +    "prod": {
      +      "description": "nbm: nbe | nbs.",
      +      "type": [
      +        "string",
      +        "null"
      +      ]
      +    },
      +    "product": {
      +      "description": "obs: CLI | METAR_R | ASOS.",
      +      "type": [
      +        "string",
      +        "null"
      +      ]
      +    },
      +    "rows": {
      +      "description": "As-issued rows; every row has origin (live | bf:<tool>) and, for runs, fetched_at; markets rows have served_at (the markets run that first served the values) and build (the deployed commit).",
      +      "items": {
      +        "additionalProperties": true,
      +        "required": [
      +          "origin"
      +        ],
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "select": {
      +      "anyOf": [
      +        {
      +          "additionalProperties": false,
      +          "properties": {
      +            "asof": {
      +              "type": [
      +                "string",
      +                "null"
      +              ]
      +            },
      +            "cycle": {
      +              "type": [
      +                "integer",
      +                "null"
      +              ]
      +            },
      +            "date": {
      +              "type": [
      +                "string",
      +                "null"
      +              ]
      +            },
      +            "lead": {
      +              "type": [
      +                "integer",
      +                "null"
      +              ]
      +            },
      +            "run": {
      +              "type": [
      +                "string",
      +                "null"
      +              ]
      +            }
      +          },
      +          "type": "object"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ],
      +      "description": "The selection asked for (run, lead, cycle; history: asof; nbm: date)."
      +    },
      +    "stn": {
      +      "description": "Station (nbm, obs).",
      +      "type": [
      +        "string",
      +        "null"
      +      ]
      +    },
      +    "table": {
      +      "description": "History table (markets: what /api/v1/markets served, one row per change, CONTRACTS §43).",
      +      "enum": [
      +        "daily",
      +        "nbm",
      +        "obs",
      +        "markets"
      +      ]
      +    },
      +    "to": {
      +      "description": "Last target date.",
      +      "type": "string"
      +    },
      +    "units": {
      +      "description": "Units of the columns.",
      +      "type": "string"
      +    },
      +    "url": {
      +      "description": "The place page.",
      +      "type": [
      +        "string",
      +        "null"
      +      ]
      +    },
      +    "v": {
      +      "const": 1,
      +      "description": "Body version."
      +    },
      +    "view": {
      +      "description": "nbm: raw | day.",
      +      "type": [
      +        "string",
      +        "null"
      +      ]
      +    }
      +  },
      +  "required": [
      +    "v",
      +    "kind",
      +    "table",
      +    "asof",
      +    "from",
      +    "to",
      +    "n_rows",
      +    "columns",
      +    "rows",
      +    "units",
      +    "notes",
      +    "credits",
      +    "credit_keys",
      +    "credits_url"
      +  ],
      +  "type": "object"
      +}
  4. Changed4 schema fields changed
    • changedInput schema / properties / asof / description
      Previous value: -"newest run fetched by this UTC time (no look-ahead)"New value: +"newest run fetched by this UTC time (no look-ahead); markets: each row as it stood then"
    • changedInput schema / properties / kind / description
      Previous value: -"daily (default) | nbm | obs"New value: +"daily (default) | nbm | obs | markets"
    • changedInput schema / properties / kind / enum
      Previous value: -[
      -  "daily",
      -  "nbm",
      -  "obs"
      -]New value: +[
      +  "daily",
      +  "nbm",
      +  "obs",
      +  "markets"
      +]
    • changedInput schema / properties / place / description
      Previous value: -"slug, name or ICAO (kind=daily; nbm/obs: its station)"New value: +"slug, name or ICAO (kind=daily, markets; nbm/obs: its station)"
  5. First observed

TDQS

A4.5/5.0
Behavior5/5

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

Annotations already declare read-only/idempotent/non-destructive, and the description still adds real behavioral context beyond them: the no-look-ahead guarantee, hard limits (<=366 days, 1 unit per 31 days), row provenance (fetched_at, origin with bf:* = backfilled), default TSV output, and that format=json additionally returns structuredContent.

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 and nearly waste-free, with each sentence covering a distinct concern (modes, date/run selection, provenance, format, schema URL). The density of shorthand and comma-spliced clauses makes it harder to scan than it needs to be for a 17-parameter tool.

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

Completeness4/5

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

For a 17-parameter tool with no output schema, it covers mode selection, date and run constraints, return format, and the presence of provenance columns — enough to call it correctly. It says little about the actual column shape of each kind's rows, which matters more here precisely because no output schema exists.

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?

With 100% schema coverage the per-parameter definitions are already handled, yet the description adds the interaction semantics the schema cannot: run=ISO OR lead=N with optional cycle=H OR asof=ISO as mutually alternative ways of pinning a run, plus the from/to range constraint. It doesn't explain every parameter (place, stn, source, product are left to the schema), so not a 5.

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 resource and capability — 'as-issued history for backtests (no look-ahead)' — and then names all four modes (daily, nbm, obs, markets) with a one-clause gloss of each. An agent can tell this apart from forecast/fetch-style siblings without opening the schema.

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?

The 'for backtests (no look-ahead)' framing plus the per-kind glosses (obs = 'settlement truth', markets = 'what the markets tool served') effectively route the caller to the right mode and signal that this is the retrospective tool. It never explicitly states when to prefer a sibling (e.g. forecast vs history), so it stops short of full when/when-not guidance.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources