Skip to main content
Glama
ChunSam

kiwoom-mcp-server

by ChunSam
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

ETF 수익률·NAV 추이 조회

get_etf_returns

Fetch ETF performance in three views: period returns vs. a selected benchmark index, daily NAV premium/discount with tracking error, and foreign/institutional net buying flows.

Instructions

ETF의 성과를 세 각도로 조회합니다 (키움 ka40001/ka40003/ka40008). view=period(기본)는 기간별(1주/1개월/6개월/1년) 수익률을 비교지수 수익률과 나란히 보여줍니다 — 이 비교지수는 benchmark_index_code로 직접 고르는 국내 지수이고 ETF의 추적지수와 자동으로 맞춰지지 않습니다(지정하지 않으면 201 KOSPI200이 그대로 들어갑니다). 코드는 get_market_index의 '코드' 값(001 코스피 종합, 101 코스닥 종합 등)이라 해외지수(나스닥100·S&P500 등)를 추종하는 ETF는 비교 지수를 맞출 수 없습니다 — 그때는 ETF 수익률만 읽고 지수 비교는 제공되지 않는다고 답하세요(추종 성과는 view=daily의 추적오차율). view=daily는 일별 NAV와 괴리율·추적오차 추이입니다 — 'ETF가 제값에 거래되고 있나', '지수를 잘 따라가고 있나'를 물을 때 씁니다(get_etf_info는 최신 1점만 보여줍니다). view=investor는 일자별 외국인·기관 순매수량입니다(period는 기간 합계라 해상도가 다릅니다). 종목코드를 모르면 search_stock으로 먼저 찾으세요.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
daysNoview=daily/investor의 표시 일수 (기본값 20, 최대 30)
viewNo조회 종류 (기본값: period)
stock_codeYes6자리 ETF 종목코드 (예: 069500)
benchmark_index_codeNo비교할 지수 코드 3자리 (기본값 201 KOSPI200 — get_market_index의 '코드' 값). view=period 전용이며 ETF의 추적지수와 자동으로 맞춰지지 않습니다 — 국내 지수 코드만 받습니다

Schema Changelog

Changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. Changed1 schema field changedv0.52.6
    • changedInput schema / properties / benchmark_index_code / description
      Previous value: -"비교할 지수 코드 3자리 (기본값 201 KOSPI200 — get_market_index의 '코드' 값). view=period 전용"New value: +"비교할 지수 코드 3자리 (기본값 201 KOSPI200 — get_market_index의 '코드' 값). view=period 전용이며 ETF의 추적지수와 자동으로 맞춰지지 않습니다 — 국내 지수 코드만 받습니다"
  2. Changed3 schema fields changedv0.51.0
    • changedInput schema / properties / benchmark_index_code / description
      Previous value: -"비교할 지수 코드 3자리 (기본값 201 KOSPI200 — get_market_index의 '코드' 값)"New value: +"비교할 지수 코드 3자리 (기본값 201 KOSPI200 — get_market_index의 '코드' 값). view=period 전용"
    • addedInput schema / properties / days
      Added value: +{
+  "description": "view=daily/investor의 표시 일수 (기본값 20, 최대 30)",
+  "maximum": 30,
+  "minimum": 1,
+  "type": "integer"
+}
    • addedInput schema / properties / view
      Added value: +{
+  "description": "조회 종류 (기본값: period)",
+  "enum": [
+    "period",
+    "daily",
+    "investor"
+  ],
+  "type": "string"
+}
  3. Addedv0.12.0

TDQS

A4.9/5.0
Behavior5/5

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

No annotations exist, so the description carries the full burden. It discloses the critical limitation that benchmark_index_code only accepts domestic indices and does not auto-match the ETF's tracked index, that overseas ETFs therefore lack index comparison, and that investor data has different resolution (period sums vs daily). Also notes the default KOSPI200 behavior. This is exceptional transparency for a tool with no structured annotations.

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 a single dense paragraph, but every clause carries information. It is front-loaded with the core purpose and then branches into each view. Slightly long but justified given the tool's complexity (three modes, cross-tool dependencies, edge cases). Could be broken into bullets, but the flow is logical 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?

For a tool with three view modes, a cross-referenced index code, and multiple parameter dependencies, the description covers every practical need: defaults, alternatives, limitations, and fallback instructions for overseas ETFs. Combined with 100% schema coverage and no output schema (so no return format needed), an agent has everything required to call it correctly.

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?

Even though schema_description_coverage is 100%, the description adds substantial meaning: it maps each view to concrete use cases, explains benchmark_index_code's origin from get_market_index and its non-automatic behavior, and clarifies the tracking-error context in daily view. This goes far beyond the schema's field definitions, which are already detailed but less operational.

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 ('조회'), a clear resource (ETF 성과), and enumerates three distinct angles (period, daily, investor) with concrete data types. It also explicitly differentiates from get_etf_info by noting that tool only shows the latest point, so an agent can distinguish sibling purposes.

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 when-to-use guidance: period for benchmark-relative returns, daily for NAV/tracking-error questions, investor for flow data. Names the alternative get_etf_info and the prerequisite search_stock for unknown codes. Leaves nothing to inference.

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

Install Server

Other Tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/ChunSam/kiwoom-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server