Skip to main content
Glama
T-Bank Invest MCP Server (read-only)

T-Bank Invest MCP Server (read-only)

by Sicness

get_candles

Read-only

Fetch historical OHLCV candlestick data for an instrument across a date range and interval to analyze price trends and volume.

Instructions

Get historical candles (OHLCV) for an instrument.

Returns {"columns": ["time", "open", "high", "low", "close", "volume", "volumeBuy", "volumeSell"], "candles": [...]}: one row per candle, oldest first, in the order of "columns". Volumes are in lots; the two columns splitting volume into buys and sells are there when the API has them. For day, week and month candles "time" is a date. "last_candle_complete": false appears when the last candle's period is still running — its close is the current price, not a close. A bond's prices are in percent of its nominal, not in money. Candles from before a split or a consolidation usually come recalculated to today's shares, while operations keep the prices and quantities of their day.

The API limits the period one request may span: a day for minute candles, a week for 5-10 minute ones, 3 weeks for 15-30 minute ones, 3 months for hourly ones, 6 years for daily ones. A year of daily candles is about 22,000 characters; several years of them do not fit into a client's limit — ask for weekly or monthly candles instead.

Args: instrument_id: Instrument ticker, FIGI, ISIN or UID from_date: Start date (YYYY-MM-DD), default: 30 days ago to_date: End date (YYYY-MM-DD, inclusive), default: now interval: Candle interval — CANDLE_INTERVAL_1_MIN, CANDLE_INTERVAL_5_MIN, CANDLE_INTERVAL_15_MIN, CANDLE_INTERVAL_HOUR, CANDLE_INTERVAL_DAY, CANDLE_INTERVAL_WEEK, CANDLE_INTERVAL_MONTH (also 5/10/30_SEC, 2/3/10/30_MIN, 2/4_HOUR)

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": {
      "instrument_id": "<instrument_id>"
    },
    "name": "get_candles"
  }
}

Input Schema

NameRequiredDescriptionDefault
to_dateNo
intervalNoCANDLE_INTERVAL_DAY
from_dateNo
instrument_idYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.0.0

TDQS

A4.1/5.0
Behavior5/5

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

Annotations only cover read-only and open-world; the description carries deep behavioral context beyond that: the volume-in-lots convention, the buy/sell split columns being conditionally present, the last_candle_complete flag meaning the close is a live price, bond pricing in percent of nominal, split/consolidation recalculation behavior, and the per-interval API span limits plus payload-size warnings. This is exactly the kind of non-obvious operational detail an agent needs.

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?

The response shape is front-loaded before the behavioral caveats, and nearly every sentence carries load — the split-adjustment and bond-pricing notes are non-obvious and worth their space. The trailing interval enumeration is somewhat redundant against the schema enum, a minor bloat in an otherwise dense, well-ordered description.

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?

There is no output schema, so the description must explain returns — and it does, spelling out the columns list, row ordering, and the optional volumeBuy/volumeSell fields. Combined with the covered stability flags and API limits, an agent has everything needed to call this correctly and interpret the result.

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 description coverage, the description has to carry the parameters and largely does: instrument_id accepts ticker/FIGI/ISIN/UID, from_date defaults to 30 days ago, to_date is inclusive and defaults to now, and interval is explained with additional acceptable values. It loses a point because the interval value list substantially repeats the schema enum rather than adding new meaning beyond the default.

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

Purpose4/5

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

Opens with a specific verb and resource: 'Get historical candles (OHLCV) for an instrument.' That is unambiguous and distinct from siblings like get_close_prices or get_last_prices in substance. However, it never explicitly names or contrasts those adjacent price-retrieval siblings, so the agent must infer the boundary itself.

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?

Usage context is implied through the API span limits and the advice to 'ask for weekly or monthly candles instead' when data volume is too large, which is genuine when-to-do-X guidance. But it never states when to prefer this tool over get_close_prices, get_last_prices, or get_stock_snapshot, nor any preconditions such as required instrument resolution.

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