Skip to main content
Glama

start_pairs_scan

Scan an index for pairs of stocks that move together.

    For one chosen pair (KO and PEP, say), `start_regime_analysis` with
    `ticker` and `ticker_b` checks that pair directly.

    Every account runs it within a daily allowance; a refused call does not count, and get_started and
    every run's answer give today's count.

    A scan takes about 1 to 5 minutes (every pair in the universe after
    a correlation screen). The call returns `{task_id, status, kind,
    dashboard_url}`; `get_pairs_scan_progress(task_id)` reports progress
    and, when the scan has finished, carries `result` with up to ten
    pairs, those that passed every filter and then the closest misses,
    each with its own statistics rounded (`candidates`).

    `steps` has the same shape as in `start_mr_scan`. The filters and
    their settings, defaults in brackets:
        correlation      min_corr, the lowest return correlation [0.7]
        cointegration    max_pvalue, the highest Engle-Granger p-value [0.05]
        spread_halflife  min_hl and max_hl, the spread's half-life band in
                         days [5, 60]
        beta_stability   max_cov, how much the hedge ratio may vary, in
                         percent [50]; window, bars [60]
        spread_hurst     max_h, the highest Hurst exponent of the spread [0.45]
        johansen         min_rank, the fewest cointegrating relations [1]

    Args:
        index: 'sp500', 'nasdaq100' or 'dowjones'. Asked for another index (the DAX, the FTSE 100), pass it all
            the same: QuanterLab answers with its note and the same scan on the S&P 500, and nothing runs.
        question: Optional. One sentence restating what the run should answer, not the person's
            message: the title of the report the finished run becomes, and kept only as that.

    When the run has finished, its answer also carries `report_url`: the scan written up as a QuanterLab
    report (the funnel and every pair that passed). The call waits for the run while it is likely to finish
    inside it; the run's card in the chat shows the result or, for a longer run, how far it is, and fills in
    by itself, with the next steps as choices and the report link. A run started here needs no
    `show_report_card`.
    

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": {
      "steps": "<steps>"
    },
    "name": "start_pairs_scan"
  }
}

Input Schema

NameRequiredDescriptionDefault
indexNosp500
stepsYes
durationNo3y
questionNo
timeframeNo1d

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.5/5.0
Behavior5/5

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

Goes well beyond the annotations: discloses a 1–5 minute runtime, the exact return envelope `{task_id, status, kind, dashboard_url}`, that results arrive via `get_pairs_scan_progress`, a quota that doesn't charge refused calls, the synchronous-wait behavior, and the non-obvious fact that no `show_report_card` is needed. The index-substitution behavior is a critical disclosure an agent could not infer anywhere else.

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 the purpose and the single-pair alternative before the mechanical details, and the filter list is compactly tabulated. Some of the tail — the run card filling itself in, next steps as choices, the report link — is UI chatter that dilutes rather than informs, but it is not large enough to be wasteful.

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?

With no output schema, the description fully specifies the immediate return, where the actual results live (`candidates` with up to ten pairs), and the eventual `report_url`. The remaining gap is the undocumented `duration`/`timeframe` window controls, which matter for a backtest-like scan over time series.

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 0% schema coverage the description carries the full burden, and it does so for three of five params: `index` values plus out-of-vocabulary behavior, `question` as a one-sentence report title, and a detailed filter block for `steps` (correlation, cointegration, spread_halflife, beta_stability, spread_hurst, johansen with defaults). `duration` and `timeframe` are never mentioned at all, leaving two time-window parameters undocumented in both schema and prose.

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 — scanning an index for pairs of stocks that move together — and immediately distinguishes itself from start_regime_analysis (single chosen pair) and start_mr_scan (shared `steps` shape). An agent can tell exactly which scan family this belongs to 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 Guidelines4/5

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

Explicitly routes the single-pair case to `start_regime_analysis` with `ticker`/`ticker_b`, documents the daily allowance and that refused calls don't count, and states the fallback behavior for unsupported indexes (DAX, FTSE 100 → note plus S&P 500 scan). It does not, however, say when to pick this over the sibling `start_mr_scan` mean-reversion scan, leaving the broader tool-selection choice partly implicit.

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