tossinvest-mcp

Get stock reference data

tossinvest_get_stocks

Read-onlyIdempotent

Resolve stock symbols into reference data—name, market, security type, currency, listing status, and shares outstanding—to verify a listing before trading or calculate market cap.

Instructions

Get reference/master data for one or more symbols: names, listing market, security type, currency, listing status and shares outstanding.

Use this to resolve what a symbol actually is, to check a symbol is still listed and tradable before ordering, or to get the shares-outstanding figure needed for a market-cap calculation (market cap = lastPrice x sharesOutstanding).

Args:

symbols (string): Comma-separated symbols, max 200, no spaces.
response_format ('markdown' | 'json'): default 'markdown'.

Returns { count, stocks: [{ symbol, name, englishName, isinCode, market, securityType, isCommonShare, status, currency, listDate, delistDate, sharesOutstanding, leverageFactor, koreanMarketDetail }] }.

market: KOSPI, KOSDAQ, NYSE, NASDAQ, AMEX, KR_ETC, US_ETC
securityType: STOCK, FOREIGN_STOCK, DEPOSITARY_RECEIPT, INFRASTRUCTURE_FUND, REIT, ETF, FOREIGN_ETF, ETN, STOCK_WARRANTS
status: SCHEDULED (not yet listed), ACTIVE, DELISTED
isCommonShare: false for preferred shares
koreanMarketDetail (KR symbols only): { liquidationTrading, nxtSupported, krxTradingSuspended, nxtTradingSuspended }

This does NOT search by company name — it takes symbols only. It also returns no prices; use tossinvest_get_prices for those.

Errors: 404 stock-not-found when a symbol does not exist.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`symbols`	Yes	Comma-separated stock symbols, up to 200 (e.g. '005930,000660' or 'AAPL,MSFT'). No spaces.
`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	Default
`count`	Yes
`stocks`	Yes
`truncated`	No
`truncation_message`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedv1.0.0Sep 8, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds substantial behavioral context: symbol-only lookup, no price data, status enum meanings (SCHEDULED/ACTIVE/DELISTED), KR-only koreanMarketDetail, and the exact 404 error for unknown symbols. This goes well beyond the annotations without contradicting them.

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 well-structured and front-loaded: purpose, usage guidance, args, return shape, exclusions, and errors are each in logical order. While the Args block partially duplicates the schema, the sections on return fields, enums, and error behavior add genuine value, and no sentence feels wasteful or irrelevant.

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?

The description is thorough for a tool of this complexity: it covers parameter constraints, output structure and enums, KR-specific detail, usage boundaries, and error behavior. Given the rich annotations and output schema, nothing essential is missing for an agent to correctly select and invoke this 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%: both `symbols` and `response_format` are fully described in the input schema, including the max-200 constraint, no-spaces rule, enum values, and default. The description's Args section largely restates this information and adds no meaningful new semantic detail beyond what the schema already provides, so the baseline of 3 applies.

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: 'Get reference/master data for one or more symbols', listing the exact fields returned. It also explicitly distinguishes itself from siblings by noting it does NOT search by company name and returns no prices, directing agents to tossinvest_get_prices for prices. This makes its purpose unambiguous relative to similar data tools.

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?

Provides explicit usage scenarios: resolve what a symbol actually is, verify listing/tradability before ordering, and compute market cap via shares outstanding. It also states clear exclusions ('does NOT search by company name', 'returns no prices') and names the alternative tool for prices, giving agents concrete when-to-use and 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