tossinvest-mcp

Get candle chart data

tossinvest_get_candles

Read-onlyIdempotent

Retrieve OHLCV price candles for any stock to analyze trends, ranges, and moving averages. Choose daily or 1-minute intervals, paginate backward using nextBefore, and get up to 200 bars per request.

Instructions

Get OHLCV candles for one stock, newest bar first. Max 200 bars per call.

This is the tool for historical price analysis: trends, ranges, moving averages, "how did X do last month".

Args:

symbol (string): One symbol.
interval ('1m' | '1d'): 1-minute or daily bars.
count (number): 1-200, default 100.
before (string, optional): ISO 8601 upper bound, inclusive — only bars at or before this instant. Pass the previous response's nextBefore to page backwards in time. Omit for the newest bars.
adjusted (boolean): default true. Adjust for splits/dividends. Set false for raw prices.
response_format ('markdown' | 'json'): default 'markdown'.

Returns { symbol, interval, count, candles: [{ timestamp, openPrice, highPrice, lowPrice, closePrice, volume, currency }], nextBefore }. timestamp is the bar's OPEN time. nextBefore is null when no older data exists.

Examples:

"Samsung's last 30 trading days" -> symbol='005930', interval='1d', count=30
"Apple intraday today" -> symbol='AAPL', interval='1m', count=200
For indices use tossinvest_get_market_indicator_candles instead.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`count`	No	Number of bars to return (max 200).
`before`	No	Inclusive upper bound (ISO 8601). Only bars at or before this instant. Use the previous response's nextBefore to page backwards.
`symbol`	Yes	Stock symbol. KRX: 6 digits (e.g. '005930' for Samsung Electronics). US: ticker (e.g. 'AAPL').
`adjusted`	No	Apply split/dividend adjustment. Default true.
`interval`	Yes	Candle interval: '1m' = 1-minute bars, '1d' = daily bars.
`response_format`	No	Output format: 'markdown' for a compact human-readable summary, 'json' for the complete raw payload.	markdown

Output Schema

TableJSON Schema

Name	Required	Description
`count`	Yes
`symbol`	Yes
`candles`	Yes	Newest bar first
`interval`	Yes
`truncated`	No
`nextBefore`	No	Pass as `before` to fetch the next (older) page; null when no more data
`truncation_message`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedv1.0.0Sep 8, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations already mark this as read-only, idempotent, and non-destructive, so the description does not need to restate safety. It adds significant behavioral context: bars are newest-first, the call is capped at 200 bars, pagination uses `nextBefore` from the previous response, and `nextBefore` is null when no older data exists. This makes the tool's runtime behavior predictable.

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 description is well-structured and front-loaded: core behavior first, then usage context, argument details, return shape, and examples. It is slightly redundant because the Args section largely duplicates the input schema descriptions, but the paging note, examples, and index disambiguation make the extra length worthwhile.

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?

With six parameters, two enums, pagination, and multiple sibling tools, this description covers everything an agent needs: what the tool returns, the ordering, the 200-bar cap, the paging mechanism, examples for symbol/interval/count, and an explicit exclusion for index candles. The presence of an output schema also reduces the burden of describing return fields, and the description complements it well.

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?

The input schema already provides 100% parameter coverage, so the baseline is 3. The description adds value beyond the schema by explaining how to use `before` with `nextBefore` for backward pagination, clarifying `adjusted` behavior ('Set false for raw prices'), and offering concrete natural-language to parameter mappings in the examples. It does repeat some schema content, but the added semantics justify a 4.

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?

The description begins with a specific verb-resource statement: 'Get OHLCV candles for one stock, newest bar first.' It clearly identifies the data type (OHLCV candles), the scope (one stock), and the ordering convention. This differentiates it from sibling tools like tossinvest_get_prices, tossinvest_get_orderbook, and especially tossinvest_get_market_indicator_candles.

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?

The description explicitly frames this as the tool for historical price analysis with concrete examples like trends, ranges, moving averages, and 'how did X do last month.' It also explicitly routes index-related requests to tossinvest_get_market_indicator_candles instead, giving the agent a clear decision rule among siblings.

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

Deploy Server