tossinvest-mcp

Get stock rankings

tossinvest_get_rankings

Read-onlyIdempotent

Get top stock leaderboards by traded value, volume, or price change for Korean or US markets over selected periods. Find most active stocks, top gainers, and largest losers.

Instructions

Get a top-100 stock leaderboard by traded value, traded volume, or price change, for the Korean or US market over a chosen period.

This is the discovery tool: "what is moving today", "most actively traded Korean stocks this week", "biggest losers this month".

Args:

type: which leaderboard, and implicitly which metric it is sorted by: MARKET_TRADING_AMOUNT — highest traded value, whole market MARKET_TRADING_VOLUME — highest traded volume, whole market TOP_GAINERS — largest price gain (does NOT support duration='realtime') TOP_LOSERS — largest price drop (does NOT support duration='realtime') TOSS_SECURITIES_TRADING_AMOUNT — highest traded value among Toss Securities fills only TOSS_SECURITIES_TRADING_VOLUME — highest traded volume among Toss Securities fills only
market_country ('KR' | 'US'): which market.
duration ('realtime' | '1d' | '1w' | '1mo' | '3mo' | '6mo' | '1y'): ranking period, in trading days.
exclude_investment_caution (boolean): default false. Filter out symbols under a caution designation.
count (number): 1-100, default 100.
response_format ('markdown' | 'json'): default 'markdown'.

Returns { type, marketCountry, duration, count, rankedAt, rankings: [{ rank, symbol, currency, price: { lastPrice, basePrice, changeRate }, tradingVolume, tradingAmount }] }.

Reading the numbers correctly:

tradingVolume / tradingAmount are cumulative over 'duration'. For TOSS_SECURITIES_* they count Toss Securities fills only; otherwise the whole market.
price.basePrice and price.changeRate are measured from the START of 'duration' for TOP_GAINERS/TOP_LOSERS, but against the PREVIOUS CLOSE for every other type.
Fewer than 'count' items can come back (symbols whose quote lookup failed are dropped).
An uncomputed combination returns an empty list with rankedAt null — not an error.

Symbols come back without names; pass them to tossinvest_get_stocks to resolve company names.

Errors: 400 unsupported-ranking-duration for TOP_GAINERS/TOP_LOSERS with duration='realtime'.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`type`	Yes	Which leaderboard. TOP_GAINERS/TOP_LOSERS cannot be combined with duration='realtime'.
`count`	No	Number of ranked entries to return (max 100).
`duration`	Yes	Ranking period in trading days. 'realtime' is unavailable for TOP_GAINERS/TOP_LOSERS.
`market_country`	Yes	'KR' for Korean stocks, 'US' for US stocks.
`response_format`	No	Output format: 'markdown' for a compact human-readable summary, 'json' for the complete raw payload.	markdown
`exclude_investment_caution`	No	Exclude symbols under an investment-caution designation.

Output Schema

TableJSON Schema

Name	Required	Description
`type`	Yes
`count`	Yes
`duration`	Yes
`rankedAt`	No	null when no ranking has been computed for this combination
`rankings`	Yes
`truncated`	No
`marketCountry`	Yes
`truncation_message`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedv1.0.0Sep 8, 2026

TDQS

A5/5.0

Behavior5/5

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

Annotations already mark it read-only, idempotent, and non-destructive, but the description adds rich behavioral context: cumulative volume/amount over duration, basePrice/changeRate measured from period start for gainers/losers vs previous close otherwise, the possibility of fewer than count items due to failed lookups, empty list with null rankedAt as a normal state, and explicit error codes. This goes well beyond what annotations or schema provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is structured into clear sections (purpose, args, returns, reading numbers, symbols, errors) and is front-loaded with the core purpose. Every sentence earns its place; there is no fluff or repetition. Despite its length, it remains scannable and efficient.

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?

Given the tool's complexity (6 parameters, 4 enums, output schema), the description covers all operational aspects: return shape, edge cases (fewer than count, empty lists), error conditions, cross-tool guidance, and data interpretation. Nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with descriptions for every parameter, but the description adds substantial extra meaning: it explains each 'type' enum value's sorting metric and market scope, clarifies 'duration' is in trading days, and details how to interpret the returned numbers. It enriches the schema without redundancy.

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 opens with a precise statement: 'Get a top-100 stock leaderboard by traded value, traded volume, or price change, for the Korean or US market over a chosen period.' It then provides usage examples ('what is moving today') and names the tool as the discovery tool, clearly distinguishing it from siblings like tossinvest_get_prices or tossinvest_get_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?

It explicitly frames itself as the discovery tool and gives example queries. It also directs the agent to pass symbols to tossinvest_get_stocks to resolve names, and warns about unsupported duration/type combinations. This gives clear when-to-use and even when-not-to-use guidance.

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

Deploy Server