Skip to main content
Glama
Johnhyeon

StockLens

by Johnhyeon
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

get_detailed_investor_flow

Read-onlyIdempotent

Get daily net buying and selling by investor and institution subcategories for Korean stocks, including unsettled and provisional data with correct handling.

Instructions

상세수급 - 투자자·기관별 일별 순매매 (증권사 연결 필요, JSON).

기존 get_flow 와 다른 도구다. get_flow 는 기본 데이터의 개인·외국인· 기관 3종이고, 이 도구는 증권사 Open API 로 받는 상세 구분이다.

읽을 때 반드시 지킬 것:

  • values 에 없는 항목은 값이 없는 것이고, unsettled 에 있으면 미정산(정산 전이라 아직 값이 아님)이다. 둘 다 0 이 아니다. 0 으로 읽으면 '매매 없음'이 되어 사실과 달라진다.

  • data_state 가 provisional 인 행은 확정 수치가 아니다. final 과 섞어서 합계·평균을 내지 않는다.

  • institution_total(기관계)과 그 하위 항목(금융투자·보험·투신·은행· 연기금·사모·국가 등)을 함께 더하면 두 번 센다. 기관계는 이미 하위 항목의 합이다.

  • measure 는 수량(net_quantity, 단주)과 금액(net_amount, 백만원)이 전혀 다른 값이다. 실측상 같은 항목이 3.7배까지 차이 난다. 응답의 unit 을 빼고 숫자만 인용하지 않는다.

  • 국내(KR) 전용이다. US 종목에는 이 데이터가 없다.

  • data_availability.unavailable 은 연결된 증권사가 그 항목을 주지 않는다는 뜻이다. 키움은 기관 세부 13종을 주지만 매수·매도 분해가 없고, 한국투자증권은 3종만 주지만 매수·매도를 준다.

Args: code: KR 종목코드 6자리 (단건) codes: 종목코드 목록 (최대 30개). code 와 함께 쓸 수 있다 days: 조회할 거래일 수 (기본 20, 최대 120) measure: "net_quantity"(수량) | "net_amount"(금액) source: auto|kis|kiwoom. auto 는 주 사용 증권사 하나에 고정되고, 증권사를 명시하면 strict(실패해도 다른 곳으로 대체 안 함)

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
codeNo
daysNo
codesNo
sourceNo
measureNo

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed10 schema fields changedv1.1.3
    • removedInput schema / properties / code / anyOf
      Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
    • removedInput schema / properties / code / default
      Removed value: -null
    • addedInput schema / properties / code / type
      Added value: +"string"
    • removedInput schema / properties / codes / anyOf
      Removed value: -[
-  {
-    "items": {
-      "type": "string"
-    },
-    "type": "array"
-  },
-  {
-    "type": "null"
-  }
-]
    • removedInput schema / properties / codes / default
      Removed value: -null
    • addedInput schema / properties / codes / items
      Added value: +{
+  "type": "string"
+}
    • addedInput schema / properties / codes / type
      Added value: +"array"
    • removedInput schema / properties / days / default
      Removed value: -20
    • removedInput schema / properties / measure / default
      Removed value: -"net_quantity"
    • removedInput schema / properties / source / default
      Removed value: -"auto"
  2. Addedv1.0.1

TDQS

A5/5.0
Behavior5/5

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses critical behavioral rules: values absent or unsettled are not zero, provisional data must not be mixed with final data, institution_total already includes sub-items so adding them double counts, quantity vs amount measures differ by up to 3.7x, and per-broker availability differences (Kiwoom vs Korea Investment). No contradiction with annotations.

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?

Although lengthy, the description is well-structured and front-loaded: summary, then differentiation from get_flow, then mandatory reading warnings, then Args. Every sentence adds value, and the use of bullets and bold makes the critical data-interpretation traps skimmable.

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 tool is complex and the schema is minimal, but the description covers the key pitfalls: zero vs unsettled semantics, provisional/final data, double-counting, units, KR-only scope, broker differences, and parameter constraints. Since an output schema exists, return structure is not required. Nothing an agent needs to call this tool 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?

With 0% schema description coverage, the description carries the full burden and does so thoroughly: code (6-digit KR), codes (max 30, combinable with code), days (default 20, max 120), measure (net_quantity/net_amount meanings), and source (auto|kis|kiwoom with strict fallback behavior). All five parameters are semantically explained beyond the bare schema.

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 '상세수급 - 투자자·기관별 일일 순매매' and clearly identifies the resource: daily net trading by investor/institution. It explicitly distinguishes itself from the sibling get_flow by stating that get_flow covers the basic three groups while this tool provides the detailed brokerage breakdown. The purpose is unambiguous.

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 tool explicitly frames when to use it versus the sibling: 'get_flow provides the basic data's individual/foreign/institutional 3 types, and this tool is the detailed breakdown via brokerage Open API.' It also clearly states the tool is domestic-only: 'KR only. US stocks don't have this data.' This gives the agent direct routing guidance.

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

Deploy Server

Other Tools