Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@KIS MCP Server what's the current price of Samsung Electronics (005930)?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
한국투자증권 Open API를 Claude에서 직접 사용할 수 있는 MCP 서버입니다.
KIS Developers 에서 앱키/앱시크리트 발급
Node.js 22+ 및 npm 설치
Related MCP server: TossInvest MCP
# 실전투자 (필수)
export KIS_APP_KEY="your_app_key"
export KIS_APP_SECRET="your_app_secret"
export KIS_ACCOUNT_NO="12345678" # 계좌번호 앞 8자리
export KIS_ACCOUNT_PROD="01" # 계좌상품코드 (기본값: 01)
# 모의투자 (선택)
export KIS_PAPER_APP_KEY="your_paper_app_key"
export KIS_PAPER_APP_SECRET="your_paper_app_secret"
export KIS_PAPER_ACCOUNT_NO="12345678"npm install
npm run build프로젝트 루트 또는 ~/.claude/ 에 추가:
{
"mcpServers": {
"kis": {
"command": "node",
"args": ["/path/to/koreainvestment-mcp/dist/index.js"],
"env": {
"KIS_APP_KEY": "your_app_key",
"KIS_APP_SECRET": "your_app_secret",
"KIS_ACCOUNT_NO": "12345678",
"KIS_PAPER_APP_KEY": "your_paper_app_key",
"KIS_PAPER_APP_SECRET": "your_paper_app_secret",
"KIS_PAPER_ACCOUNT_NO": "12345678"
}
}
}
}개발 중에는 tsx로 직접 실행 가능:
{
"mcpServers": {
"kis": {
"command": "npx",
"args": ["tsx", "/path/to/koreainvestment-mcp/src/index.ts"],
"env": { "...": "..." }
}
}
}도구 | 설명 | 읽기전용 |
| 국내주식 현재가 조회 | ✅ |
| 국내주식 일/주/월별 시세 | ✅ |
| 국내주식 잔고 조회 | ✅ |
| 투자계좌 자산 현황 (실전 전용) | ✅ |
| 국내주식 현금 주문 | ❌ |
| 국내주식 주문 정정/취소 | ❌ |
| 해외주식 현재가 조회 | ✅ |
| 해외주식 일/주/월별 시세 | ✅ |
| 해외주식 잔고 조회 | ✅ |
| 해외주식 주문 | ❌ |
| 종목코드·종목명 검색 | ✅ |
| 종목 마스터 DB 현황 | ✅ |
env="real" 주문 도구는 실제 자금이 사용됩니다. 테스트는 반드시 env="demo"를 사용하세요.
주문 도구의 기본값은 env="demo"(모의투자)로 설정되어 있습니다.
실전투자와 모의투자의 앱키/계좌번호는 별개입니다.
토큰은 프로세스 메모리에 캐시되며 만료 5분 전에 자동 재발급됩니다.
종목 마스터 데이터는 ~/.kis_mcp/master.db에 저장되며 하루 1회 자동 갱신됩니다.
투자계좌의 자산 현황을 조회합니다 (실전 전용). 자산 유형별 비중 및 총 평가금액을 반환합니다.
| Name | Required | Description | Default |
|---|---|---|---|
| account_no | No | 계좌번호 앞 8자리 (미입력 시 환경변수 사용) | |
| account_prod | No | 계좌상품코드 (미입력 시 환경변수 사용) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full behavioral disclosure. It describes a read operation (조회) with no side effects, and specifies the returned data (weights and total evaluation). This is sufficiently transparent for a query tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no filler, front-loading the core action and adding output details. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple query tool with two optional parameters and no output schema, the description explains the input and output sufficiently. It lacks details on error handling or response format, but is complete enough for an agent to understand the tool's purpose and usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptive parameter names and descriptions. The description does not add additional meaning beyond what the schema already provides, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it queries account assets, specifies it is for real accounts only, and describes the output (asset type weights and total evaluation). It distinguishes itself from sibling tools like balance checks by focusing on overall asset status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions '실전 전용' (real account only) as a usage condition, but does not explicitly state when to use this tool versus alternatives like kis_get_domestic_balance or kis_get_overseas_balance. Usage context is implied but not differentiated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
국내주식 계좌의 보유 종목 잔고를 조회합니다. 수량·매입단가·평가금액·수익률 등을 반환합니다.
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | 'real'(실전) 또는 'demo'(모의) | real |
| account_no | No | 계좌번호 앞 8자리 (미입력 시 환경변수 사용) | |
| account_prod | No | 계좌상품코드 2자리 (미입력 시 환경변수 사용) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The verb '조회' implies a read-only query, but no explicit statement of side effects, authentication needs, or rate limits is given. With no annotations, the description only partially conveys the tool's safety profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the core purpose, no extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (3 optional parameters, no output schema), the description covers the main purpose and return data adequately. However, it could mention the output format (list/object) for completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the description adds no extra parameter context. It does not elaborate on parameter usage or defaults beyond what is in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it inquires the balance of held stocks in a domestic stock account, specifying returned fields (quantity, purchase price, valuation, profit rate). This distinguishes it from siblings like overseas balance and stock price tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., account assets for broader view, stock price for current price). The description does not mention when not to use or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
국내주식 일/주/월/년별 OHLCV 데이터를 날짜 범위로 조회합니다. 날짜 미지정 시 최근 데이터 반환.
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | 'real' 또는 'demo' | real |
| market | No | 시장코드: J(KRX, 기본값), NX, UN | J |
| period | No | 기간구분: D(일봉), W(주봉), M(월봉), Y(년봉) | D |
| adjusted | No | 수정주가: '1'(반영, 기본값), '0'(미반영) | 1 |
| end_date | No | 종료일 YYYYMMDD (예: '20241231', 미입력 시 오늘) | |
| start_date | No | 시작일 YYYYMMDD (예: '20240101', 미입력 시 최초일) | |
| stock_code | Yes | 종목코드 6자리 (예: '005930') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility. It mentions OHLCV data, period types, and default date behavior. However, it does not disclose other behavioral aspects such as whether it is read-only, error handling for invalid stock codes, rate limits, pagination, or data limits. The coverage is adequate for a simple query tool but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single Korean sentence that efficiently conveys the core purpose and a key behavioral note. It is front-loaded with the primary action and resource. While very brief, every part adds value and there is no superfluous text. Could be slightly more structured but remains effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 7 parameters and no output schema, the description is insufficiently complete. It fails to describe the return format, order of data points, or any constraints on date ranges. Without an output schema, the agent has no information on what the response structure looks like, limiting its ability to interpret results properly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, providing baseline meaning for each parameter. The description adds value by explaining that date range is implicit and that omitting dates returns recent data—information not explicit in the schema. It also reinforces the period meanings. Thus, it adds meaningful context beyond the structured schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the tool's function: retrieving OHLCV data for domestic stocks with period granularity (daily/weekly/monthly/yearly) and date range. The verb '조회' (retrieve) and resource 'domestic stock chart' are specific. However, it does not explicitly differentiate from the sibling tool kis_get_domestic_stock_price, which likely returns simpler data, missing a chance to clarify scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a usage hint: '날짜 미지정 시 최근 데이터 반환' (returns recent data if date not specified), indicating when to omit date parameters. However, it offers no guidance on when to use this tool versus alternatives like kis_get_domestic_stock_price or kis_get_overseas_stock_chart, nor any exclusion conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
국내주식 현재가 시세를 조회합니다. 현재가·전일대비·등락률·거래량·시가총액·PER·PBR 등을 반환합니다.
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | 'real'(실전) 또는 'demo'(모의) | real |
| market | No | 시장코드: J(KRX, 기본값), NX(NXT), UN(통합) | J |
| stock_code | Yes | 종목코드 6자리 (예: '005930' 삼성전자) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations absent, so description carries burden. It implies read-only but doesn't explicitly state no side effects, rate limits, or auth needs. Return values listed, which is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first states purpose, second lists outputs. No wasted words, front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, so description compensates by listing return fields. Explains three parameters. Could detail data format but sufficient for a common price query.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions. Description adds no extra parameter meaning beyond output context, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool queries domestic stock current price quotes and lists specific return fields (e.g., PER, PBR), distinguishing it from chart or overseas siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use vs alternatives like 'kis_get_domestic_stock_chart' or 'kis_get_overseas_stock_price'. No when-not-to-use or prerequisites mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
해외주식 계좌의 보유 종목 잔고를 조회합니다.
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | 'real' 또는 'demo' | real |
| currency | No | 통화코드: USD(미국), HKD(홍콩), CNY(중국), JPY(일본), VND(베트남) | USD |
| exchange | No | 거래소코드: NASD(미국전체)/SEHK/SHAA/SZAA/TKSE/HASE/VNSE | NASD |
| account_no | No | 계좌번호 앞 8자리 | |
| account_prod | No | 계좌상품코드 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It only states a read operation ('조회합니다') but fails to mention any potential side effects, authorization requirements, rate limits, or pagination behavior. For a simple inquiry tool, this is insufficient to fully inform the AI agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no redundancy. It efficiently conveys the tool's purpose without unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there is no output schema, the description could explain what the response contains (e.g., list of stocks, quantities). However, for a straightforward balance inquiry with fully documented parameters, the description is adequate but not comprehensive. The tool's complexity is low, so a score of 3 is reasonable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter having a brief description. The tool description adds no additional meaning beyond the schema. According to the guidelines, baseline 3 is appropriate when schema coverage is high and description adds no extra semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: inquiring the holding stock balance of overseas stock accounts. It uses a specific verb ('조회합니다') and resource ('해외주식 계좌의 보유 종목 잔고'), which distinguishes it from sibling tools like kis_get_domestic_balance (domestic) and kis_get_overseas_stock_price (price).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. The purpose is implied by the name and description (overseas stock balance), but there is no mention of prerequisites, when not to use, or how it compares to similar tools like kis_get_account_assets.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
해외주식 일/주/월별 OHLCV 데이터를 조회합니다.
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | 'real' 또는 'demo' | real |
| period | No | 기간: '0'(일봉, 기본값), '1'(주봉), '2'(월봉) | 0 |
| symbol | Yes | 종목코드 (예: 'AAPL') | |
| exchange | Yes | 거래소코드 (NAS/NYSE/AMEX/SEHK 등) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description does not disclose behavioral traits such as read-only nature, authentication needs, or rate limits. Only states basic function.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence effectively conveying the tool's purpose. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and 4 parameters, the description is too sparse. Lacks details on return format, data range, or caveats, leaving the agent underinformed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so description adds minimal value beyond schema. The tool description mentions OHLCV but does not elaborate on parameter usage beyond what schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool queries overseas stock OHLCV data for daily, weekly, or monthly periods. It distinguishes from siblings like domestic versions and overseas price tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. Lacks context on prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
해외주식 현재 체결가를 조회합니다. 미국·홍콩·중국·일본·베트남 주식 지원.
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | 'real' 또는 'demo' | real |
| symbol | Yes | 종목코드 (예: 'AAPL', 'TSLA') | |
| exchange | Yes | 거래소코드: NAS(나스닥), NYSE(뉴욕), AMEX, SEHK(홍콩), SHAA(중국상해), SZAA(중국심천), TKSE(일본), HASE(베트남하노이), VNSE(베트남호치민) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must cover behavioral traits. It states it retrieves current price but lacks details on rate limits, authentication needs, data freshness, error handling, or whether the response contains a single price or multiple fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, immediately states the core purpose, and avoids unnecessary words. It is well-structured and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (3 parameters, no output schema), the description provides basic context. However, it does not explain the return format, currency, or potential errors, which would be helpful for a stock price tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with clear descriptions for each parameter. The tool description adds modest context about supported exchanges but does not significantly enhance understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves current overseas stock prices and specifies supported markets (US, Hong Kong, China, Japan, Vietnam). It distinguishes from sibling tools like 'kis_get_domestic_stock_price' which handles domestic stocks, and 'kis_get_overseas_stock_chart' which deals with chart data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for overseas stock price queries but does not explicitly state when to use this tool versus alternatives, nor does it mention when not to use it. No guidance on prerequisites or scenarios is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
로컬 종목 마스터 DB의 시장별 종목 수와 마지막 갱신일을 조회합니다.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description indicates a read-only query, which is transparent. However, without annotations, it carries the full burden but adds no details about rate limits, authentication, or edge cases (e.g., empty DB). It is adequate but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, concise Korean sentence that contains no redundancy. Every word is necessary and informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no parameters and a straightforward purpose, the description is nearly complete. It could optionally specify the output format (e.g., a list of markets with counts and dates), but the current version suffices.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so schema coverage is 100%. The description adds meaning by specifying what the tool returns (number of stocks per market, last update date), which exceeds the schema's empty definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool queries the local stock master DB for market-wise stock counts and last update date. It uses a specific verb ('queries') and resource, distinguishing it from sibling tools that deal with prices, charts, orders, or balances.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. It does not mention prerequisites, exclusions, or contexts where other sibling tools would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
국내주식 현금 매수/매도 주문을 제출합니다. env='real'이면 실제 자금이 사용됩니다.
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | 'demo'(모의, 기본값) 또는 'real'(실전, 실제 자금 사용 주의!) | demo |
| side | Yes | 'buy'(매수) 또는 'sell'(매도) | |
| price | Yes | 주문단가 (예: '75000', 시장가이면 '0') | |
| exchange | No | 거래소: 'KRX'(기본값), 'NXT' | KRX |
| quantity | Yes | 주문수량 (예: '10') | |
| account_no | No | 계좌번호 앞 8자리 | |
| order_type | No | 주문구분: '00'(지정가, 기본값), '01'(시장가) | 00 |
| stock_code | Yes | 종목코드 6자리 (예: '005930') | |
| account_prod | No | 계좌상품코드 2자리 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description bears the burden of behavioral disclosure. It warns that env='real' uses actual funds, which is important. However, it does not explain order settlement, cancellation rules, or response behavior, leaving significant gaps for a trading tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise with one clear sentence and a specific warning. It is front-loaded with the core action. However, it omits necessary details like response expectations, making it somewhat under-specified.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (9 parameters, no output schema), the description is incomplete. It does not explain the return value, error scenarios, or order lifecycle. A trading tool should provide more context for safe invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds minimal value beyond the schema, only restating the env warning already present in the schema's parameter description. No additional parameter meaning is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool submits domestic stock cash buy/sell orders, which is a specific verb+resource. However, it does not explicitly distinguish from sibling tools like 'kis_place_overseas_order' or 'kis_revise_or_cancel_domestic_order', though the name and context imply domestic scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, such as when to place an order versus search stocks or check balances. The description only mentions the env parameter's real vs demo mode, but does not help the agent decide between siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
해외주식 매수/매도 주문을 제출합니다. env='real'이면 실제 자금이 사용됩니다.
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | 'demo'(모의, 기본값) 또는 'real'(실전, 실제 자금 사용 주의!) | demo |
| side | Yes | 'buy'(매수) 또는 'sell'(매도) | |
| price | Yes | 주문단가 (시장가이면 '0') | |
| symbol | Yes | 종목코드 (예: 'AAPL') | |
| exchange | Yes | 거래소코드: NASD(나스닥), NYSE(뉴욕), AMEX, SEHK(홍콩), SHAA, SZAA, TKSE, HASE, VNSE | |
| quantity | Yes | 주문수량 | |
| account_no | No | 계좌번호 앞 8자리 | |
| order_type | No | 주문구분: '00'(지정가, 기본값) | 00 |
| account_prod | No | 계좌상품코드 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It mentions the behavioral trait that env='real' uses real funds, which is critical. However, it does not cover other behavioral aspects such as irreversibility, authorization needs, or rate limits. Adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences, no fluff, and effectively front-loads the purpose. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given this is a financial order placement tool with 9 parameters, 5 required, and no output schema, the description is too brief. It lacks information about order confirmation, error handling, or processing behavior, leaving the agent underinformed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the description adds no additional meaning beyond the schema. It does not explain or highlight any parameters, so it meets the baseline of 3 without adding value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool submits overseas stock buy/sell orders, specifying '해외주식' to distinguish it from domestic order tools. It also includes the env warning, which adds context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for overseas orders but does not explicitly state when to use this tool versus alternatives like kis_place_domestic_order. No exclusions or when-not-to-use guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
미체결 국내주식 주문을 정정하거나 취소합니다. 이미 체결된 주문은 취소 불가합니다.
| Name | Required | Description | Default |
|---|---|---|---|
| env | No | 'demo'(모의, 기본값) 또는 'real'(실전, 실제 자금 사용 주의!) | demo |
| price | No | 정정 주문단가 (취소 시 '0') | 0 |
| action | Yes | 'revise'(정정) 또는 'cancel'(취소) | |
| all_qty | No | 잔량전부여부: 'Y'(전량, 기본값), 'N'(일부) | Y |
| exchange | No | 거래소: 'KRX'(기본값), 'NXT', 'SOR' | KRX |
| quantity | No | 주문수량 ('0'이면 잔량 전체) | 0 |
| account_no | No | 계좌번호 앞 8자리 | |
| order_type | Yes | 주문구분 (원주문과 동일, 예: '00') | |
| account_prod | No | 계좌상품코드 | |
| org_order_no | Yes | 원주문번호 | |
| org_order_orgno | Yes | 한국거래소전송주문조직번호 (원주문의 krx_fwdg_ord_orgno) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that only unexecuted orders can be revised/canceled, and executed orders cannot be canceled. With no annotations, this adds value, but it lacks details on side effects, idempotency, or rate limits, which are important for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, no wasted words. The action (revise or cancel) is front-loaded, making it efficient for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 11 parameters and no output schema, the description is too minimal. It lacks context on required fields, what org_order_orgno refers to, success/failure behavior, and prerequisites. More completeness is needed for safe use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with all parameters described in Korean, so baseline is 3. The description itself adds no extra meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it revises or cancels unexecuted domestic stock orders, using specific verbs 'revise' and 'cancel' with the resource 'domestic orders'. It distinguishes from sibling tools like kis_place_domestic_order (which places new orders) and kis_get_* (which read data).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for unexecuted orders but does not explicitly state when to use this tool versus alternatives. No 'when not to use' or alternative tool names are provided, leaving the agent to infer context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
종목코드 또는 종목명으로 종목을 검색합니다. 국내(KOSPI/KOSDAQ)·해외(미국·홍콩·일본 등) 전 종목 지원. 마스터 데이터는 하루 1회 자동 갱신됩니다 (첫 호출 시 다운로드, 수 초 소요).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | 최대 반환 수 (기본값: 10) | |
| query | Yes | 종목코드 또는 종목명 (예: '삼성전자', '005930', 'AAPL', '애플') | |
| markets | No | 검색 대상 market 목록 (기본값: 전체). KOSPI, KOSDAQ, NAS, NYS, AMS, HKS, TSE, SHS, SZS, HNX, HSX |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided. The description adds that master data is updated once per day and the first call triggers a download taking a few seconds, which is a useful behavioral trait. However, it does not disclose other aspects like rate limits, read-only nature, or error scenarios.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences. The main action is front-loaded, followed by scope and a note on data freshness. It earns its space with no redundancy, though a single sentence could have sufficed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with no output schema, the description covers essential context: what you can search, market scope, and data update behavior. However, it does not specify the output format (e.g., list of stocks with codes/names), which might be inferred but is not explicit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with clear descriptions for query, limit, and markets. The description adds minimal extra semantics (market scope, data refresh) but mostly repeats what the schema already conveys. Baseline 3 is appropriate as the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Search stocks by stock code or stock name' and specifies support for domestic (KOSPI/KOSDAQ) and overseas (US, Hong Kong, Japan, etc.) markets. This clearly defines the verb-search and resource-stocks, and distinguishes from sibling tools like kis_get_domestic_stock_price or kis_place_domestic_order which focus on other operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for finding stocks before performing other operations, but does not explicitly state when to use it versus alternative tools. No 'when-not' guidance or direct mention of sibling tools is provided. However, the purpose is clearly distinct from siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0kis_get_account_assetskis_get_domestic_balancekis_get_domestic_stock_chartkis_get_domestic_stock_pricekis_get_overseas_balancekis_get_overseas_stock_chartkis_get_overseas_stock_pricekis_master_statuskis_place_domestic_orderkis_place_overseas_orderkis_revise_or_cancel_domestic_orderkis_search_stockScored across 12 tools
Each tool has a clearly distinct purpose: domestic vs. overseas stock operations, price vs. chart vs. balance vs. order, plus search and master status. No overlapping functionality.
All tools follow a consistent 'kis_verb_noun' pattern with snake_case, making it easy to predict tool names and understand their role. E.g., 'kis_get_domestic_stock_price', 'kis_place_overseas_order'.
12 tools cover a comprehensive set of operations for stock trading (domestic and overseas): price, chart, balance, orders, account assets, search, and master data. The count is well-scoped for the domain.
Covers core stock trading operations but lacks a tool to query pending order status after placement. The order revision/cancel tool exists, implying need for order lookup. This is a notable gap.
Market analyst tools + AI agent: crypto, US equities, options, Korea, fundamentals, macro, backtests
Agentic brokerage access to a US brokerage account: quotes, orders, positions, cash and documents.
Global stock research, ML forecasts, valuation signals, screeners & portfolio tracking in Claude
Search company disclosures and financial statements from the Korean market. Retrieve stock profile…
