Skip to main content
Glama
Sign In

Voyscout Price History

by com.voyscout
OverviewDiscussionsAdmin

Find opportunities

find_opportunities
Read-only

Use when the user asks where it is unusually cheap right now without naming a destination ("kde je teď levně?", "where is it cheap right now?"). Rank every published rail by how its LAST measurement compares with its own tracked history, so a caller can ask 'where is it unusually cheap right now?' in one call instead of one call per destination. Each row is ONE rail, so a destination with several rails can appear once per rail with different numbers: name the rail when you cite a row. Read searched before interpreting a price: it is the TRIP the series was collected for (the search mode, and the fixed travel dates where there are any - a Christmas series is not the price of a summer trip), while measured is when we observed it; price_covers says what the money buys and origins the departure-airport cluster. Percentages are over observed days, not the calendar span. latest_cheaper_than_pct_of_days is the same number as cheaper_than_pct under a name that states its direction (higher = cheaper than more of the tracked days). stale_rails says how many of the rails THIS call matched are past their own freshness boundary today, with the day it was judged (as_of), so the caller need not subtract dates per row. Descriptive only: it ranks observations and gives no verdict. Rails with too little history are returned under excluded, never dropped silently. When you answer from this, say where the latest price sits in its own history and stop there: do not tell the reader to buy, book, wait, avoid or which destination to pick - the series carries no trend, volatility or live availability, so that judgement stays the reader's.

Input Schema

NameRequiredDescriptionDefault
railNooptional: restrict to one rail
sortNooptional (default cheapest_vs_history): 'cheapest_vs_history' ranks by the share of tracked days that were dearer; 'most_below_median' ranks by how far the last measurement sits below the median, relatively
limitNooptional (default 10): how many rows to return; 'matched' reports the count before the cap
partyNooptional: '<adults>-<children>', e.g. '2-2' - the same A-C shape the price streams are keyed on. A well-formed party no rail carries returns `no_coverage` with the parties that exist
min_history_daysNooptional (default 30): rails measured for fewer days are listed under 'excluded'

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changed
    • changedInput schema / properties / party / description
      Previous value: -"optional: '<adults>-<children>', e.g. '2-2' - the same A-C shape the price streams are keyed on"New value: +"optional: '<adults>-<children>', e.g. '2-2' - the same A-C shape the price streams are keyed on. A well-formed party no rail carries returns `no_coverage` with the parties that exist"
    • addedInput schema / properties / party / pattern
      Added value: +"^(0|[1-9]\\d*)-(0|[1-9]\\d*)$"
    • changedOutput schema / anyOf
      Previous value: -[
-  {
-    "properties": {
-      "currency": {
-        "type": "string"
-      },
-      "disclaimer": {
-        "type": "string"
-      },
-      "excluded": {
-        "items": {
-          "properties": {
-            "destination": {
-              "type": "string"
-            },
-            "history_days": {
-              "type": "integer"
-            },
-            "rail": {
-              "enum": [
-                "flight",
-                "package"
-              ],
-              "type": "string"
-            },
-            "reason": {
-              "type": "string"
-            },
-            "resort_key": {
-              "type": "string"
-            }
-          },
-          "required": [
-            "destination",
-            "rail",
-            "reason",
-            "history_days"
-          ],
-          "type": "object"
-        },
-        "type": "array"
-      },
-      "generated": {
-        "description": "the OLDEST `generated` among the rows returned",
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "license": {
-        "properties": {
-          "attribution": {
-            "type": "string"
-          },
-          "id": {
-            "type": "string"
-          },
-          "url": {
-            "type": "string"
-          }
-        },
-        "required": [
-          "id",
-          "url",
-          "attribution"
-        ],
-        "type": "object"
-      },
-      "matched": {
-        "description": "rows before the `limit` cap",
-        "type": "integer"
-      },
-      "min_history_days": {
-        "type": "integer"
-      },
-      "opportunities": {
-        "items": {
-          "properties": {
-            "cheaper_than_pct": {
-              "type": [
-                "number",
-                "null"
-              ]
-            },
-            "destination": {
-              "type": "string"
-            },
-            "generated": {
-              "type": "string"
-            },
-            "history_days": {
-              "type": "integer"
-            },
-            "is_series_min": {
-              "type": "boolean"
-            },
-            "latest": {
-              "type": [
-                "number",
-                "null"
-              ]
-            },
-            "latest_cheaper_than_pct_of_days": {
-              "type": [
-                "number",
-                "null"
-              ]
-            },
-            "latest_stale_after_days": {
-              "type": "number"
-            },
-            "measured": {
-              "properties": {
-                "days": {
-                  "type": "integer"
-                },
-                "from": {
-                  "type": "string"
-                },
-                "to": {
-                  "type": "string"
-                }
-              },
-              "required": [
-                "days",
-                "from",
-                "to"
-              ],
-              "type": "object"
-            },
-            "median": {
-              "type": [
-                "number",
-                "null"
-              ]
-            },
-            "min": {
-              "type": [
-                "number",
-                "null"
-              ]
-            },
-            "party": {
-              "properties": {
-                "adults": {
-                  "type": "integer"
-                },
-                "children": {
-                  "type": "integer"
-                }
-              },
-              "required": [
-                "adults",
-                "children"
-              ],
-              "type": "object"
-            },
-            "rail": {
-              "enum": [
-                "flight",
-                "package"
-              ],
-              "type": "string"
-            },
-            "resort": {
-              "type": "string"
-            },
-            "resort_key": {
-              "type": "string"
-            },
-            "title": {
-              "properties": {
-                "cs": {
-                  "type": "string"
-                },
-                "en": {
-                  "type": "string"
-                }
-              },
-              "required": [
-                "cs",
-                "en"
-              ],
-              "type": "object"
-            },
-            "url": {
-              "type": "string"
-            }
-          },
-          "required": [
-            "destination",
-            "title",
-            "url",
-            "rail",
-            "party",
-            "latest",
-            "median",
-            "min",
-            "cheaper_than_pct",
-            "latest_cheaper_than_pct_of_days",
-            "is_series_min",
-            "history_days",
-            "measured",
-            "generated"
-          ],
-          "type": "object"
-        },
-        "type": "array"
-      },
-      "schema": {
-        "type": "string"
-      },
-      "sort": {
-        "enum": [
-          "cheapest_vs_history",
-          "most_below_median"
-        ],
-        "type": "string"
-      },
-      "stale_rails": {
-        "description": "How many of the rails in scope are past their own freshness boundary on `as_of` (Europe/Prague).",
-        "properties": {
-          "as_of": {
-            "type": "string"
-          },
-          "count": {
-            "type": "integer"
-          },
-          "keys": {
-            "items": {
-              "type": "string"
-            },
-            "type": "array"
-          },
-          "of": {
-            "type": "integer"
-          },
-          "unknown": {
-            "type": "integer"
-          }
-        },
-        "required": [
-          "as_of",
-          "of",
-          "count",
-          "keys"
-        ],
-        "type": "object"
-      }
-    },
-    "required": [
-      "schema",
-      "generated",
-      "sort",
-      "min_history_days",
-      "matched",
-      "stale_rails",
-      "opportunities",
-      "excluded",
-      "disclaimer"
-    ],
-    "type": "object"
-  },
-  {
-    "description": "tool-level failure, returned with isError: true",
-    "properties": {
-      "error": {
-        "additionalProperties": true,
-        "properties": {
-          "code": {
-            "type": "string"
-          },
-          "message": {
-            "type": "string"
-          }
-        },
-        "required": [
-          "code",
-          "message"
-        ],
-        "type": "object"
-      }
-    },
-    "required": [
-      "error"
-    ],
-    "type": "object"
-  }
-]New value: +[
+  {
+    "properties": {
+      "currency": {
+        "type": "string"
+      },
+      "disclaimer": {
+        "type": "string"
+      },
+      "excluded": {
+        "items": {
+          "properties": {
+            "destination": {
+              "type": "string"
+            },
+            "history_days": {
+              "type": "integer"
+            },
+            "rail": {
+              "enum": [
+                "flight",
+                "package"
+              ],
+              "type": "string"
+            },
+            "reason": {
+              "type": "string"
+            },
+            "resort_key": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "destination",
+            "rail",
+            "reason",
+            "history_days"
+          ],
+          "type": "object"
+        },
+        "type": "array"
+      },
+      "generated": {
+        "description": "the OLDEST `generated` among the rows returned",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "license": {
+        "properties": {
+          "attribution": {
+            "type": "string"
+          },
+          "id": {
+            "type": "string"
+          },
+          "url": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "id",
+          "url",
+          "attribution"
+        ],
+        "type": "object"
+      },
+      "matched": {
+        "description": "rows before the `limit` cap",
+        "type": "integer"
+      },
+      "min_history_days": {
+        "type": "integer"
+      },
+      "no_coverage": {
+        "description": "present only when NO published rail carries the requested party: a coverage limit, distinct from an empty ranking",
+        "properties": {
+          "available_parties": {
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          },
+          "message": {
+            "type": "string"
+          },
+          "party": {
+            "type": "string"
+          },
+          "rail": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "party",
+          "rail",
+          "available_parties",
+          "message"
+        ],
+        "type": "object"
+      },
+      "opportunities": {
+        "items": {
+          "properties": {
+            "arrivals": {
+              "description": "arrival airports RECORDED; covers_all_published_prices is false",
+              "type": "object"
+            },
+            "cheaper_than_pct": {
+              "type": [
+                "number",
+                "null"
+              ]
+            },
+            "destination": {
+              "type": "string"
+            },
+            "generated": {
+              "type": "string"
+            },
+            "history_days": {
+              "type": "integer"
+            },
+            "is_series_min": {
+              "type": "boolean"
+            },
+            "latest": {
+              "type": [
+                "number",
+                "null"
+              ]
+            },
+            "latest_cheaper_than_pct_of_days": {
+              "type": [
+                "number",
+                "null"
+              ]
+            },
+            "latest_stale_after_days": {
+              "description": "this rail's own freshness boundary, in days after measured.to",
+              "type": "number"
+            },
+            "measured": {
+              "properties": {
+                "days": {
+                  "type": "integer"
+                },
+                "from": {
+                  "type": "string"
+                },
+                "to": {
+                  "type": "string"
+                }
+              },
+              "required": [
+                "days",
+                "from",
+                "to"
+              ],
+              "type": "object"
+            },
+            "median": {
+              "type": [
+                "number",
+                "null"
+              ]
+            },
+            "min": {
+              "type": [
+                "number",
+                "null"
+              ]
+            },
+            "origins": {
+              "description": "departure-airport CLUSTER; covers_all_published_prices is false",
+              "type": "object"
+            },
+            "party": {
+              "properties": {
+                "adults": {
+                  "type": "integer"
+                },
+                "children": {
+                  "type": "integer"
+                }
+              },
+              "required": [
+                "adults",
+                "children"
+              ],
+              "type": "object"
+            },
+            "price_covers": {
+              "description": "what the money buys - airfare only, or a package as offered",
+              "type": "object"
+            },
+            "rail": {
+              "enum": [
+                "flight",
+                "package"
+              ],
+              "type": "string"
+            },
+            "regime_breaks": {
+              "description": "[from, to] date spans where the series was not comparable",
+              "type": "array"
+            },
+            "resort": {
+              "type": "string"
+            },
+            "resort_key": {
+              "type": "string"
+            },
+            "searched": {
+              "description": "the search mode (and fixed dates, where there are any) the series was collected under, and `stay_nights` {from, to}: how long a trip each point prices - the flight and package rails of one destination can differ",
+              "type": "object"
+            },
+            "stats": {
+              "properties": {
+                "basis": {
+                  "type": "string"
+                },
+                "cheaper_than_pct": {
+                  "type": [
+                    "number",
+                    "null"
+                  ]
+                },
+                "is_series_max": {
+                  "type": "boolean"
+                },
+                "is_series_min": {
+                  "type": "boolean"
+                },
+                "latest": {
+                  "type": [
+                    "number",
+                    "null"
+                  ]
+                },
+                "median": {
+                  "type": [
+                    "number",
+                    "null"
+                  ]
+                },
+                "min": {
+                  "type": [
+                    "number",
+                    "null"
+                  ]
+                }
+              },
+              "required": [
+                "basis"
+              ],
+              "type": "object"
+            },
+            "title": {
+              "properties": {
+                "cs": {
+                  "type": "string"
+                },
+                "en": {
+                  "type": "string"
+                }
+              },
+              "required": [
+                "cs",
+                "en"
+              ],
+              "type": "object"
+            },
+            "url": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "destination",
+            "title",
+            "url",
+            "rail",
+            "party",
+            "price_covers",
+            "measured",
+            "stats",
+            "latest",
+            "median",
+            "min",
+            "cheaper_than_pct",
+            "latest_cheaper_than_pct_of_days",
+            "is_series_min",
+            "history_days",
+            "measured",
+            "generated"
+          ],
+          "type": "object"
+        },
+        "type": "array"
+      },
+      "schema": {
+        "type": "string"
+      },
+      "sort": {
+        "enum": [
+          "cheapest_vs_history",
+          "most_below_median"
+        ],
+        "type": "string"
+      },
+      "stale_rails": {
+        "description": "How many of the rails in scope are past their own freshness boundary on `as_of` (Europe/Prague).",
+        "properties": {
+          "as_of": {
+            "type": "string"
+          },
+          "count": {
+            "type": "integer"
+          },
+          "keys": {
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          },
+          "of": {
+            "type": "integer"
+          },
+          "unknown": {
+            "type": "integer"
+          }
+        },
+        "required": [
+          "as_of",
+          "of",
+          "count",
+          "keys"
+        ],
+        "type": "object"
+      }
+    },
+    "required": [
+      "schema",
+      "generated",
+      "sort",
+      "min_history_days",
+      "matched",
+      "stale_rails",
+      "opportunities",
+      "excluded",
+      "disclaimer"
+    ],
+    "type": "object"
+  },
+  {
+    "description": "tool-level failure, returned with isError: true",
+    "properties": {
+      "error": {
+        "additionalProperties": true,
+        "properties": {
+          "code": {
+            "type": "string"
+          },
+          "message": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "code",
+          "message"
+        ],
+        "type": "object"
+      }
+    },
+    "required": [
+      "error"
+    ],
+    "type": "object"
+  }
+]
  2. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "anyOf": [
+    {
+      "properties": {
+        "currency": {
+          "type": "string"
+        },
+        "disclaimer": {
+          "type": "string"
+        },
+        "excluded": {
+          "items": {
+            "properties": {
+              "destination": {
+                "type": "string"
+              },
+              "history_days": {
+                "type": "integer"
+              },
+              "rail": {
+                "enum": [
+                  "flight",
+                  "package"
+                ],
+                "type": "string"
+              },
+              "reason": {
+                "type": "string"
+              },
+              "resort_key": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "destination",
+              "rail",
+              "reason",
+              "history_days"
+            ],
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "generated": {
+          "description": "the OLDEST `generated` among the rows returned",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "license": {
+          "properties": {
+            "attribution": {
+              "type": "string"
+            },
+            "id": {
+              "type": "string"
+            },
+            "url": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "id",
+            "url",
+            "attribution"
+          ],
+          "type": "object"
+        },
+        "matched": {
+          "description": "rows before the `limit` cap",
+          "type": "integer"
+        },
+        "min_history_days": {
+          "type": "integer"
+        },
+        "opportunities": {
+          "items": {
+            "properties": {
+              "cheaper_than_pct": {
+                "type": [
+                  "number",
+                  "null"
+                ]
+              },
+              "destination": {
+                "type": "string"
+              },
+              "generated": {
+                "type": "string"
+              },
+              "history_days": {
+                "type": "integer"
+              },
+              "is_series_min": {
+                "type": "boolean"
+              },
+              "latest": {
+                "type": [
+                  "number",
+                  "null"
+                ]
+              },
+              "latest_cheaper_than_pct_of_days": {
+                "type": [
+                  "number",
+                  "null"
+                ]
+              },
+              "latest_stale_after_days": {
+                "type": "number"
+              },
+              "measured": {
+                "properties": {
+                  "days": {
+                    "type": "integer"
+                  },
+                  "from": {
+                    "type": "string"
+                  },
+                  "to": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "days",
+                  "from",
+                  "to"
+                ],
+                "type": "object"
+              },
+              "median": {
+                "type": [
+                  "number",
+                  "null"
+                ]
+              },
+              "min": {
+                "type": [
+                  "number",
+                  "null"
+                ]
+              },
+              "party": {
+                "properties": {
+                  "adults": {
+                    "type": "integer"
+                  },
+                  "children": {
+                    "type": "integer"
+                  }
+                },
+                "required": [
+                  "adults",
+                  "children"
+                ],
+                "type": "object"
+              },
+              "rail": {
+                "enum": [
+                  "flight",
+                  "package"
+                ],
+                "type": "string"
+              },
+              "resort": {
+                "type": "string"
+              },
+              "resort_key": {
+                "type": "string"
+              },
+              "title": {
+                "properties": {
+                  "cs": {
+                    "type": "string"
+                  },
+                  "en": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "cs",
+                  "en"
+                ],
+                "type": "object"
+              },
+              "url": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "destination",
+              "title",
+              "url",
+              "rail",
+              "party",
+              "latest",
+              "median",
+              "min",
+              "cheaper_than_pct",
+              "latest_cheaper_than_pct_of_days",
+              "is_series_min",
+              "history_days",
+              "measured",
+              "generated"
+            ],
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "schema": {
+          "type": "string"
+        },
+        "sort": {
+          "enum": [
+            "cheapest_vs_history",
+            "most_below_median"
+          ],
+          "type": "string"
+        },
+        "stale_rails": {
+          "description": "How many of the rails in scope are past their own freshness boundary on `as_of` (Europe/Prague).",
+          "properties": {
+            "as_of": {
+              "type": "string"
+            },
+            "count": {
+              "type": "integer"
+            },
+            "keys": {
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            },
+            "of": {
+              "type": "integer"
+            },
+            "unknown": {
+              "type": "integer"
+            }
+          },
+          "required": [
+            "as_of",
+            "of",
+            "count",
+            "keys"
+          ],
+          "type": "object"
+        }
+      },
+      "required": [
+        "schema",
+        "generated",
+        "sort",
+        "min_history_days",
+        "matched",
+        "stale_rails",
+        "opportunities",
+        "excluded",
+        "disclaimer"
+      ],
+      "type": "object"
+    },
+    {
+      "description": "tool-level failure, returned with isError: true",
+      "properties": {
+        "error": {
+          "additionalProperties": true,
+          "properties": {
+            "code": {
+              "type": "string"
+            },
+            "message": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "code",
+            "message"
+          ],
+          "type": "object"
+        }
+      },
+      "required": [
+        "error"
+      ],
+      "type": "object"
+    }
+  ],
+  "type": "object"
+}
  3. Added

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), and the description adds substantial behavioral context beyond them: descriptive-only with no verdict, low-history rails surfaced under `excluded` rather than dropped, `stale_rails` freshness judgement with `as_of`, and the explicit caveat that the series carries no trend, volatility or live availability.

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-loads the usage trigger, then moves through output interpretation in a dense, purposeful sequence. It is long (~250 words) and repeats the 'unusually cheap right now' framing, but nearly every sentence carries an interpretive constraint that would otherwise be missed.

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?

Despite having an output schema, it supplies the interpretive context an agent needs to read the rows correctly: rail-level row semantics, the direction sign of the cheaper-than percentage, day-based vs calendar-based percentages, and freshness handling. Complete for a zero-required-parameter screening tool.

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 description coverage is 100% and each parameter is already documented in the schema, so the baseline is 3. The description adds meaning mostly about output fields (`searched`, `measured`, `price_covers`, `origins`) rather than input parameters; it does not extend sort/limit/rail semantics beyond what the schema states.

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 precise verb+resource and scope: it ranks every published rail by how its latest measurement compares with that rail's own tracked history, and frames it as the one-call alternative to 'one call per destination', which implicitly distinguishes it from destination-scoped siblings. An agent can tell this apart from price_history or compare_destinations without opening a schema.

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

Usage Guidelines5/5

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

Gives an explicit trigger with bilingual example utterances ('kde je teď levně?'), a contrast condition (without naming a destination), and downstream guidance on what to say from the answer and what not to claim (no buy/book/wait/avoid verdict).

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

All Voyscout Price History 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