kiwoom-mcp-server
Server Quality Checklist
Latest release: v0.52.6
- Disambiguation4/5
Tools are generally well-separated by resource (account, stock, order, market, sector, theme, ETF, gold) and specific action (holdings, trend, today, balance, transactions, pending orders, executions, etc.). Some potential confusion exists among the many market data tools (e.g., get_daily_trading vs get_investor_trend vs get_execution_strength) but descriptions explicitly cross-reference each other to clarify boundaries.
Naming Consistency3/5Naming follows a mixed but mostly readable convention: 'get_' plus noun_qualifier (e.g., get_account_holdings, get_stock_quotes, get_orderbook_rank). Some inconsistency: get_ping vs ping, and get_account_today vs get_account_balance (vs get_account_trend) — the pattern is not uniform. Also 'get_trading_journal' vs 'get_transactions' are semantically distinguishable but naming doesn't strongly hint at the difference.
Tool Count2/549 tools is far above the typical well-scoped range of 3-15, and even above the generous 16-25 heavy range. However, the server covers a broad domain (Korean stock market, accounts, orders, market data, ETF, gold) and each tool maps to specific Kywoom API TR codes, so the count is justified by the domain's complexity, but it still feels overwhelming for an agent to select from.
Completeness4/5The tool surface is extensive: account queries (mostly read-only, no order placement), market data with many screening tools, and special asset classes (ETF, gold, derivatives). Major gaps: there is no tool to place or cancel orders (despite pending orders being viewable), and no options or futures. Also, some account tools are not available in simulation mode. However, for a read-heavy analysis server, the coverage is strong.
Average 4.5/5 across 49 of 49 tools scored. Lowest: 3.8/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 115 commits in the last 12 weeks
- Last stable release on
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
This repository includes a glama.json configuration file.
If you are the author, simply .
If the server belongs to an organization, first add
glama.jsonto the root of your repository:{ "$schema": "https://glama.ai/mcp/schemas/server.json", "maintainers": [ "your-github-username" ] }Then . Browse examples.
Add related servers to improve discoverability.
How to sync the server with GitHub?
Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.
To manually sync the server, click the "Sync Server" button in the MCP server admin interface.
How is the quality score calculated?
The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).
Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.
Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).
Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.
Tool Scores
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry behavioral disclosure. It reveals the tool reads historical short selling data and lists the returned fields, but does not mention rate limits, error conditions, data range limits, or confirm it is non-destructive. The source reference (키움 ka10014) adds credibility but not behavioral detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with front-loaded purpose and data details. No redundant words; each sentence adds essential information. The structure is optimal for quick parsing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 3 parameters and no output schema, the description adequately covers the tool's purpose and data fields. It mentions default period and date customization. However, it does not specify output format (list vs. single record), pagination, or any constraints on date range length, leaving some gaps for a time-series tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with parameter descriptions, so baseline is 3. The description adds value by explaining the default date range (30 days) and that the tool returns multiple data points per date, which enriches understanding beyond raw schema fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool inquires daily short selling trends for a specific stock, listing specific data fields (closing price, fluctuation rate, volume, short selling volume, ratio, average price). This distinguishes it from siblings like get_stock_lending and get_investor_trend, which cover different data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit guidance on when to use this tool vs. alternatives (e.g., get_stock_lending). It only mentions the default 30-day period and that dates can be customized, but does not state prerequisites, limitations, or exclusion cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It mentions internal API codes (ka40002, etc.) but does not explicitly state read-only behavior, authentication needs, or rate limits. Adequate but lacks explicit safety characteristics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first states the action and APIs used, second gives a usage tip. Front-loaded with essential information, no redundant words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but the description lists the returned fields (tracking index, tax type, price, NAV, discrepancy). Could be improved by specifying output format or structure, but overall sufficient for a simple one-parameter tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with pattern and example. The description adds the practical tip about using search_stock but does not add new semantic meaning beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool queries ETF information including tracking index, tax type, current price, NAV, and discrepancy. It distinguishes itself from siblings like get_etf_returns by specifying multiple data sources and mentions using search_stock for unknown codes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises using search_stock first if the stock code is unknown, providing a clear alternative. Does not differentiate from get_etf_returns or other ETF-related tools, but the context of 'ETF info' implies its scope.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must bear the burden. It adds useful context (max 30 stocks, internal code, alert statuses in remarks) but does not explicitly state that the tool is read-only or idempotent, nor mention rate limits or error behaviors. A score of 3 is appropriate given the lack of 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose and data fields, followed by usage guidance and a note about alert statuses. No redundant or vague phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 1 parameter and no output schema, the description covers the returned fields (price, change, volume, amount, market cap, remarks) and usage context. It could mention error handling or output formatting but is otherwise complete for a batch query tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents the parameter. The description repeats the parameter constraints (6-digit codes, 1-30 items) and provides an example. This adds no significant value beyond the schema, so baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it queries current price, change rate, volume, transaction amount, market cap, and alert statuses for multiple stocks. It distinguishes itself from sibling get_stock_price by explicitly recommending this tool for batch queries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to use this when needing quotes for 2+ stocks and to avoid repeated calls to get_stock_price. It implies not to use for single stocks but does not explicitly state the alternative, though it is clear enough for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description reveals it is a read operation and mentions the 2-month constraint. However, it does not disclose authentication requirements, rate limits, or behavior when no data is found. It adds value but could be more thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first states purpose and return data, second details parameter behavior. No redundancy, perfectly front-loaded with essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description summarizes key output fields (per-stock prices, quantities, profit/loss, totals). It references the API source but does not describe the exact output structure (e.g., list vs object). Mostly complete for a daily journal.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description reiterates the same information about base_date (default today, last 2 months). It adds no new meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads a daily trading journal for a specific date, listing details like average buy/sell price, quantity, profit/loss, and return rates. It references the specific API (ka10170), distinguishing it from siblings like get_account_holdings or get_transactions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use it (for a specific date, defaults to today) and constraints (only within last 2 months). It does not explicitly exclude alternatives, but the context is clear enough for an agent to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It discloses parameter interactions (stock_code overrides market, potential empty results), lists return fields (발동가격, 괴리율, etc.), and identifies the data source (키움 ka10054). It lacks details like sorting/pagination or whether the data is real-time, but for a lookup tool, it provides substantial behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficient and front-loaded. The first sentence clearly states the purpose, and the following dash-separated clauses compactly summarize parameter options and special behavior. It is concise yet informative, with no filler content, though it is slightly dense due to the parameter enumeration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters, no output schema, and no annotations, the description does a good job covering the essentials: purpose, parameter defaults, parameter interactions, and return fields. It does not explicitly describe the output format or sorting order, but these are not critical for a simple retrieval tool. The mention of the underlying system (ka10054) adds useful context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds some semantic value by translating enum values (상승/하락, 정적/동적) and explaining the consequence of stock_code/market mismatch ('종목의 시장과 어긋나면 결과가 비므로'). However, much of the parameter information is already present in the schema descriptions, so the added value is marginal.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: '당일 변동성완화장치(VI)가 발동된 종목을 조회합니다' (retrieve stocks that triggered VI today). It specifies the resource (VI-triggered stocks), the verb (조회/retrieve), and lists the key data fields returned (발동가격, 괴리율, 등). This clearly distinguishes it from sibling tools like get_market_movers or get_stock_quotes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use the tool: for retrieving VI-triggered stocks. It explains parameter defaults and the precedence rule for stock_code over market, including a practical warning about mismatched markets leading to empty results. However, it does not explicitly mention when not to use it or suggest alternative tools, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description discloses first call delay (few seconds due to master download) and 12-hour cache, and that caution status appears in notes. Fills the gap left by missing 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise (4 sentences) with key information front-loaded: purpose, when to use, behavioral notes. Slightly verbose with the internal code mention but overall well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple search tool with no output schema, description covers input, caching behavior, returned information (code, caution status). Adequate for correct agent invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and describes the query parameter adequately. Description adds context about scope (KOSPI/KOSDAQ, ETFs/ETNs) but does not significantly enhance parameter understanding beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it searches stocks by name or code to find stock codes for KOSPI/KOSDAQ including ETF/ETN, referencing internal code. It distinguishes from sibling tools which are data retrieval tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises to use this tool first when stock code is unknown before passing to other tools. While it doesn't list when not to use, the guidance is clear and contextually sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that the operation is a retrieve (조회), lists output fields, and notes that no arguments are required. However, it does not explicitly state that it is read-only, mention error conditions, or authentication requirements. Adequate for a simple getter 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence. The main action is front-loaded ('조회합니다'), and the detailed field list is appended logically. No wasted words or redundancy with the title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no parameters and no output schema, the description is fully complete. It enumerates the exact return fields, identifies the data source (키움 kt00018), and confirms no arguments are needed. No additional context is required for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the description explicitly states '인자가 필요 없습니다' (no arguments needed). This goes beyond the baseline for zero-parameter tools, providing clear confirmation and eliminating any ambiguity about invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves the account's holdings list and enumerates the specific fields returned (quantity, average price, current price, valuation amount, profit/loss, return rate, weight). This distinguishes it from sibling tools like get_account_balance, which focus on balance rather than held stocks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when holdings are needed but provides no explicit alternative guidance or when-not-to-use conditions. It does not compare with other account-related tools, leaving the agent to infer from the tool name and sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that the tool returns both period totals and recent daily records, and mentions the 'unit' parameter. However, it does not explicitly confirm read-only behavior, mention rate limits, or describe error handling or data freshness. While not contradictory, it lacks deeper behavioral context for a query tool beyond its 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph but densely packed with useful information: purpose, output content, unit explanation, alternative tools, and fallback for unknown code. Each sentence serves a distinct purpose, and there is no fluff. The structure is logical and front-loaded with the core purpose, making it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (4 parameters, no output schema, no annotations), the description is quite complete. It explains output (period totals and daily records), unit choices, and provides clear usage guidance. However, since there is no output schema, it could have elaborated on the exact fields returned (e.g., columns for each investor type), but it covers the essential functionality well.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already provides clear descriptions for all parameters (e.g., unit default, date formats). The description adds minimal extra meaning, such as clarifying that 'unit' values are amount (million won, default) and quantity. Since the schema is already comprehensive, the description is adequate but does not significantly enhance parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to query net buying trends by investor type (individual/foreign/institution) for a stock, and differentiates it from sibling tools by explicitly naming alternatives (get_daily_trading, get_institution_trend, get_net_buy_rank). The verb '조회' (query) and resource '종목' (stock) are specific, and it includes API codes for precision.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool versus alternatives, including specific cases: 'get_daily_trading(view=flow)' for daily trading details with close/volume/program/credit, 'get_institution_trend' for estimated average cost, and 'get_net_buy_rank' for finding stocks by market participant. It also directs users to 'search_stock' if the stock code is unknown. This is exemplary differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It discloses the source, output structure, and cross-references. While it doesn't mention auth or rate limits, for a read operation this is sufficient and adds value beyond a basic description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero waste. The first sentence states the purpose, the second adds structural detail and cross-reference. Information is front-loaded and every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description provides essential context about the output format (first row composite, then sectors) and how to use the results. It is complete enough for a simple market index tool, though it omits pagination or limits which are likely unnecessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one parameter (market) with enum and description, achieving 100% coverage. The description does not add additional meaning beyond what the schema already provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves KOSPI/KOSDAQ composite and sector indices, referencing the source code ka20003. It also explains the output structure (first row composite, subsequent sector indices) and how the code field links to other tools, which distinguishes it from siblings like get_sector_price.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context on when to use the tool (for market and sector indices) and hints at a workflow by noting that the code can be used with get_sector_price/get_sector_stocks. It does not explicitly state when not to use or compare with alternatives, but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the read-only nature and lists returned fields. It does not cover rate limits or authentication, but the read-only behavior is sufficient for this type of tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with purpose, and includes only relevant details: fields returned, filter option, and read-only nature. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with one optional parameter and no output schema, the description is fairly complete. It explains input, output fields, and behavior. However, it lacks details on response format or pagination.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter stock_code. The description reiterates the same information as the schema's description, adding no extra meaning. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves pending order lists from an account, listing specific fields (order number, stock, buy/sell type, etc.) and explicitly mentions it is read-only and does not execute orders. This distinguishes it from siblings like get_account_balance or get_transactions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the tool is read-only with no order execution, and mentions optional filtering by stock_code. It gives clear context but does not explicitly compare to alternatives or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses a behavioral trait: ambiguous sector names return errors with candidate codes, and it references the underlying Kiwoom API codes (ka20004~ka20008/ka20019). It does not cover rate limits or auth, but the disclosed ambiguity handling adds meaningful transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences that front-load the main purpose and embed essential period and sector code details without any fluff. Every sentence earns its place, and it is efficiently structured for quick parsing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's purpose, period options, and sector code semantics, which is sufficient given the detailed schema. It does not describe the return format, but the tool is a chart retrieval and the schema covers all parameters, so the context is mostly complete. Minor gap: no explicit description of the output structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds Korean translations for period values (e.g., '일봉', '주봉') and clarifies that sector_code can be a name or code, but these are largely redundant with the schema. The cross-reference to get_market_index provides modest added value, but not enough to score higher.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves candle charts for sector indices, with a specific verb ('조회합니다' = retrieves) and resource ('업종 지수의 캔들 차트'). It lists period options and sector code formats, distinguishing it from sibling tools like get_sector_price or get_stock_chart.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: use this tool for sector index charts, and it cross-references get_market_index for sector code sourcing. It does not explicitly mention alternatives or when not to use it, which keeps it a step below a perfect 5, but the context is clear enough for an agent to select it appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It adds behavioral context by naming the Kiwoom API (ka20001) and enumerating the returned data fields, but it does not disclose output format, pagination, rate limits, or explicitly confirm read-only nature (though '조회' implies it). This 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary purpose and data fields, followed by parameter guidance. Every clause contributes essential information, and the formatting is clean and scannable. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description enumerates the key return components (index, open/high/low, volume, rising/falling counts, 52-week high/low, time-series trends), which gives a good sense of the response. It also fully covers the single parameter. It lacks explicit differentiation from nearby siblings, but the detailed field list helps. Overall, it is quite complete for a simple query tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema already describes sector_code with examples and error behavior. The description adds value by referencing get_market_index as the code source and reinforcing that sector names are acceptable. This goes beyond the schema's details, so a score above baseline is warranted.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves current price details of a sector index, listing specific data fields (index, open/high/low, volume, etc.). It distinguishes itself from sibling tools like get_sector_stocks or get_sector_chart by focusing on '현재가 상세' (current price details) and referencing a specific backend API. The verb '조회합니다' unambiguously indicates a read operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool: to get detailed current price information for a sector index. It also tells users how to obtain the sector_code via get_market_index and that sector names are accepted. However, it does not explicitly exclude alternatives or state when not to use this tool, so it falls short of a perfect score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description effectively discloses that the tool retrieves daily estimated data combining two sources, includes specific financial metrics, and has a usage limit (max 90 days). It does not mention side effects, authentication needs, or data freshness, but the read-only nature is implied and consistent with the tool's purpose.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise, consisting of two sentences that front-load the main purpose, then provide a usage example and limitation. No unnecessary words or repetition. It earns its place with clean structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has one well-documented parameter, no output schema, and no annotations, the description is complete: it explains what data is returned, the period range, and an important exclusion (simulated trading). No critical information is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter 'days', with the schema already providing description and constraints. The description adds minimal extra value by repeating the default and max values and giving a usage example. Baseline 3 is appropriate as the description does not significantly augment the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb '조회' (retrieve) and the resource '계좌 자산·수익률 추이' (account asset/return trends), detailing specific components like daily estimated deposit assets and period returns. It distinguishes from siblings by mentioning it's not supported for simulated trading and by specifying the data sources (키움 kt00002 + kt00016).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a typical query example ('내 계좌가 지난 한 달간 어떻게 변했나'), default (30 days) and maximum (90 days) period, and explicitly states it is not supported for simulated trading. However, it does not explicitly compare with sibling tools or give when-not-to-use advice beyond the simulation restriction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the unique feature of estimated average cost per entity and explains a use case (comparing current price vs average to spot trapped/profitable investors). It also mentions the underlying API code (키움 ka10062), adding context. However, it does not discuss output details or data freshness, keeping it from a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each earning its place: first states core function, second differentiates and adds interpretive value, third explains a parameter and points to alternatives. Front-loaded with key information, no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 5 parameters, 100% schema coverage, but no output schema. The description explains the purpose, unique average-price feature, and usage direction, but does not clarify the return structure (e.g., columns, order, pagination) or data update timing. Given no output schema, the description should provide more on what the response contains, leaving a clear gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents all 5 parameters with descriptions and defaults (100% coverage). The description adds marginal value by explaining the direction parameter in the context of the tool's core concept, but it largely repeats what the schema states. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with a specific verb '조회' and resource: ranking of stocks where institutions and foreigners net-trade in the same direction. It also explicitly distinguishes itself as the only tool providing estimated average prices per entity, setting it apart from sibling tools like get_net_buy_rank and get_investor_trend.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear when-to-use guidance: use this when you need simultaneous same-direction trades and average prices. It explicitly names alternatives for different needs: '주체별로 따로 보려면 get_net_buy_rank(마감 후 12주체)나 get_investor_trend(종목별)를 쓰세요' and highlights the unique value proposition.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the use of adjusted prices (수정주가 반영) and references Kiwoom API codes, adding behavioral context. It does not contradict any annotations (none provided) and is consistent with a read-only operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, using one key sentence plus additional detail in the following sentences. It packs important information without redundancy, though the second sentence could be better structured for readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description should ideally mention the response format (e.g., OHLCV data). It covers input parameters well but lacks details on what the returned data looks like, leaving the agent slightly uncertain about the output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds significant value by explaining the period enum values in Korean, clarifying default values for period, minute_scope, and tick_scope, and showing the relationship between period and the sub-parameters. This goes beyond the schema's enum lists.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves candlestick chart data for a stock, specifies the resource (캔들 차트 데이터) and verb (조회), and differentiates from sibling tools like search_stock by advising to use search_stock if the stock code is unknown.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool (to get chart data) and provides a prerequisite (use search_stock if stock code unknown). It does not explicitly state when not to use, but the context makes it clear this is for chart data rather than simple price queries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description discloses it takes zero arguments and returns a fixed message, fully describing its simple behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two succinct sentences front-loading purpose, no wasted words. Ideal for a simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, no-output-schema tool, description completely covers purpose and behavior without gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with zero parameters; description confirms no arguments, adding no new info beyond schema. Baseline 3 appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly identifies the tool as a health check for the Kiwoom MCP server, using specific verbs ('verify') and resource ('server connection'), distinct from sibling tools that focus on data retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states to use for server verification, implying use before operations. Could mention no alternatives, but context with siblings makes purpose clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It clearly identifies the operation as a read-only inquiry ('조회합니다') and provides domain context about the data's significance. However, it does not disclose potential response structure, pagination, or any side effects. The interpretation guidance adds value beyond a basic read-only declaration, but the lack of explicit safety/behavioral details keeps it from a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, using three sentences to cover purpose, interpretation, and alternatives. Every sentence adds value: the first states the core function, the second provides market interpretation, and the third distinguishes it from sibling tools. No fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 parameters with full schema coverage and no output schema, the description sufficiently explains what the tool does and when to use it. It also includes interpretation guidance that aids the agent in reasoning about results. However, it does not mention output format or pagination (though count parameter mentions 'latest first'), but this is not critical for a data-retrieval tool. The absence of annotations is compensated by the description's clarity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does 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 does not add much beyond the schema for parameters; it mentions credit_type (loan/short) by defining the terms, but the schema already describes each parameter clearly. The interpretation context indirectly helps understand what parameters mean, but no new parameter-specific details are added.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: retrieving new, repayment, and balance trends for credit loans (borrowed money to buy) or short borrowing (borrowed to sell) for a specific stock. It uses a specific verb (조회합니다/retrieves) and distinct resource (신용융자·대주 잔고 추이). It also differentiates from sibling tools by explicitly naming get_stock_lending and get_short_selling as alternatives for other data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage guidance: it states that this tool is for individual credit transactions, while get_stock_lending covers institutional/foreign securities lending and get_short_selling covers short selling volume. It also explains interpretation context (credit balance signals forced-selling pressure, short balance signals bearish bets), helping the agent decide when to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It discloses the estimated nature of the price (추정평균단가), the distinction between daily and cumulative net buying, and how to interpret the results. However, it doesn't mention any rate limits, data latency, or output format details, so it falls short of a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a compact three-sentence structure that front-loads the purpose and uses each sentence for differentiation or interpretation guidance, with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description adequately conveys what data is returned (estimated average price and daily/cumulative net buying), and how to use it. It also provides alternatives and the API code, but could specify response structure more explicitly for full completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description doesn't add meaning beyond the schema for parameters; it repeats the concept of cumulative net buying but doesn't specify parameter syntax or constraints beyond what the schema already lays out.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves estimated average buy prices for institutions/foreigners and daily/period cumulative net buying for a specific stock. It explicitly differentiates from sibling tools by noting get_investor_trend for finer investor breakdown and get_foreign_holding for foreign share holdings, and asserts this tool is the only one providing unit price.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit when-to-use and when-not-to-use guidance: use get_investor_trend for finer investor categories, get_foreign_holding for foreign ownership shares/limit ratio, and this tool when average unit price is needed. Also gives a practical interpretation context (comparing current price vs estimated price to assess profit/loss).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that data is only available during regular market hours and may return empty or zero volumes otherwise, and explains the three view modes. It does not detail return field structure, but covers key behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four concise sentences, front-loaded with the core purpose, followed by view modes, market hours, and alternatives. Every sentence provides useful information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema and no annotations, the description covers purpose, view semantics, timing constraints, and sibling alternatives. It does not specify the exact return fields, but the agent has enough contextual information to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already has 100% parameter description coverage, so the baseline is 3. The description adds only marginal extra semantics, such as the balance view including total buy/sell and net buy, but most parameter meanings are already in the schema. It does not substantially add syntax or formatting details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves stocks with thick or surging order book volumes across the entire market. It explicitly distinguishes from siblings by pointing to get_orderbook for individual stock order books and get_execution_strength for execution strength.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance, including the specific alternatives: '특정 종목 하나의 10단 호가는 get_orderbook, 체결 쪽 힘은 get_execution_strength를 쓰세요.' It also notes that the tool only computes during regular market hours, helping agents decide when it is useful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and explains the behavioral differences between rise/fall and open_rise/open_fall (previous close vs today's open), the market scanning requirement, and the inclusion of an execution strength column for open-based types. It does not disclose auth requirements or rate limits, but for a query tool this is minor.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence contributes: it front-loads the purpose, then details types, constraints, and use cases. It could be slightly more concise (e.g., removing internal API codes ka10027...), but the structure is logical and not wasteful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers parameter semantics, constraints, and use cases thoroughly for a 4-parameter tool. However, without an output schema, it only hints at return values (e.g., execution strength column for open types) and does not describe the complete result structure or pagination, leaving some completeness gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all parameters, but the description adds meaning beyond it: it explains the semantic distinction between rise/fall and open_rise/open_fall, why market is restricted for open-based types, and the purpose of min_volume and credit_ratio. This goes well beyond the schema's descriptive text.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves daily market rankings ('당일 시장 순위를 조회합니다') and enumerates the ranking types (rise, fall, volume, value, open_rise, open_fall, credit_ratio), making the purpose specific. It distinguishes from siblings by mentioning get_credit_trend for a different use case, though it does not explicitly contrast with other ranking tools like get_valuation_rank.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit conditions for when certain types are valid: open_rise/open_fall require market to be kospi or kosdaq and min_volume to narrow the population, and credit_ratio is for finding forced-sell pressure, with get_credit_trend explicitly named as the alternative for a specific stock's credit balance time series. This gives clear usage guidance, though it does not cover all possible alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses the tool returns aggregated sector data including investor-type breakdowns and index change. It also notes it fetches all sectors at once. While it doesn't mention auth or rate limits, the read-only nature is clear, and it adds context about the API key (키움 ka10051) and return contents.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core action, then a concise usage guide. Every sentence earns its place with no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description explains what is returned (per-sector net buys by investor type, index change). Combined with detailed parameter schema and explicit sibling differentiation, the tool is well-contextualized. Minor gaps like pagination or error handling, but sufficient for typical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline 3. The description adds minimal parameter-specific meaning beyond the schema, only implicitly framing the tool's purpose. No extra semantics for top, sort, unit, market, or base_date beyond what schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it retrieves net purchases by investor type for all sectors at once ('시장 전체 업종의 투자자 주체별 순매수를 한 번에 조회합니다'), with specific verb+resource. It also distinguishes from siblings by naming alternatives like get_investor_trend and get_sector_price.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use context ('오늘 돈이 어느 섹터로 갔나') and directly names alternatives for other use cases: stock-level use get_investor_trend, top stocks use get_investor_rank, sector details use get_sector_price/get_sector_stocks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses limitations (no dividend yield/dividend data because Kiwoom REST API lacks the TR) and what additional data is included (industry, listing date, trading halt/supervision warning flags). This is good transparency about coverage and edge cases, though it doesn't mention pagination, response format, or potential delays.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: the first clearly states the purpose and data returned, the second notes a specific limitation and provides navigation guidance. No wasted words, front-loaded with the key action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter query tool with no output schema, this description is complete: it specifies input format, what data to expect, what's excluded, and additional status flags. The only minor gap is not stating the response format (JSON shape), but that's often acceptable. Given the tool's simplicity and sibling context, it's well-rounded.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers the single parameter (stock_code) with a pattern and example. The description reinforces the format (6자리 종목코드) and adds that it's domestic stocks/ETFs, plus the search_stock fallback. Since schema coverage is 100% and there's only one parameter, the description adds meaningful context without redundancy.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves current price, change rate, volume, and basic indicators (PER, EPS, PBR, market cap) for a 6-digit Korean stock/ETF code. It explicitly distinguishes itself from search_stock and other stock-related siblings by focusing on current price snapshot, not charts, quotes, or sector data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: it's for querying current price and indicators by stock code, and includes a when-not-to-use note (dividend info not available via Kiwoom REST API) and a cross-reference to search_stock when only the name is known. It doesn't explicitly enumerate alternatives for other use cases, but the sibling list and clarity make usage reasonably clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It clearly discloses the tool's read-only, query-like nature via '조회합니다' and explains the conceptual meaning of supply/demand zones. However, it does not describe the output format, return fields, or any limitations (e.g., sorting, pagination) beyond what the schema covers, which keeps it from a perfect score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no wasted words. It front-loads the core purpose, then explains the interpretation/use-case, then distinguishes from alternatives. Each sentence earns its place and the overall structure is easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 6-parameter tool with no output schema and no annotations, the description is quite complete: it explains the underlying concept, when to use it, and how it differs from siblings. The only gap is that it doesn't describe the return structure or sample output, which would be helpful since no output schema exists. Nonetheless, the rich schema and clear purpose make the tool mentally invocable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with every parameter already having a clear description (defaults, ranges, and meanings). The tool description adds conceptual context about 매물대, which helps understand the parameters, but it does not enrich individual parameter semantics beyond the schema. Thus, baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('조회합니다' - retrieves) and the resource ('매물대에 몰린 종목' - stocks concentrated in supply/demand zones). It also differentiates from siblings by naming specific alternatives like get_orderbook and get_market_movers, making the unique purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on when to use this tool ('현재가 위아래 어디에 물량이 뭉쳐 있는지 확인할 때') and explicitly names alternatives for related but distinct tasks (get_orderbook for single-stock orderbook, get_market_movers for volume surges). It even states '가격대별 거래 분포를 보는 것은 이 tool뿐입니다' to emphasize exclusivity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the tool's scope (daily cash flow at a glance), lists the specific data fields returned, and highlights a major limitation (unavailable in simulated trading). It doesn't explicitly state the return format or that it's a read-only call, but for a no-parameter query tool, the provided behavioral context is strong.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences with dense but purposeful content. It leads with the primary purpose, then enumerates contents, provides sibling comparisons, states exclusivity, and closes with a limitation. Each sentence earns its place, though the listing of comma-separated metrics makes it slightly heavy. Still, it's efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-parameter, no-output-schema tool, the description covers the essential context: what data is returned, which sibling tools to use for other needs, and a key environment restriction (paper trading). It could have described the display format or the meaning of D+2, but the information provided is sufficient for an agent to decide when to invoke this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema coverage is trivially 100%. The description correctly avoids inventing parameters and instead focuses on the query's fixed scope, which is the appropriate semantic content. Per the rubric, 0 params earns a baseline of 4, and the description supports this by explaining what the single-page view includes.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'inquires about what happened in the account today at a glance' and enumerates specific content (sell/buy amounts, fees/taxes, deposits/withdrawals, D+2 estimates, credit/loan balances). It explicitly distinguishes this tool from siblings by naming get_trading_journal, get_account_holdings, and get_account_balance for related but different queries, making the purpose 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance by stating that per-stock realized P&L should use get_trading_journal, current holdings get_account_holdings, and summary balances get_account_balance, then notes 'this is the only tool for viewing daily cash flow.' It also provides a critical exclusion: not available in simulated trading (RC9000).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries the burden. It discloses the data source (키움 ka40004), the ~1,150 universe size, performance implication ('좁힐수록 조회도 빨라집니다' via tax_type filter), and a caveat that index_name matches only ~1/4 of tickers. Lacks explicit statement about safety/read-only nature or pagination, but adds meaningful behavioral context given zero 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Description is two dense sentences that pack purpose, scope, examples, and alternatives. Slightly verbose with the Korean phrasing but every clause earns its place. Could be tightened but is efficiently front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Well-completed for a screening tool with 6 params at 100% schema coverage and no output schema. Variables like sort enums and filters are well-explained in schema; description resolves the key decision of when to use it vs siblings. Missing return-format clarification but acceptable given the task type.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed param descriptions. The description adds practical context beyond schema: tax_type performance hint, min_volume filtering rationale (거래정지 종목 극단적 괴리율 제거), manager prefix-partial-match semantics, and index_name 1/4 coverage caveat. This enriches the enum and integer params with domain knowledge.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb '스크리너' + resource '상장 ETF 전 종목(약 1,150개)' + sort dimensions (괴리율·등락률·거래량·추적오차). Clearly distinguishes from ETFs-only tools (get_etf_info, get_etf_returns) and general stock screeners (get_valuation_rank, get_ranking) by stating it's for when '종목을 아직 고르지 않은 상태에서'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use ('종목을 아직 고르지 않은 상태에서 찾을 때'), and names concrete alternatives with when NOT to use (get_etf_info, get_etf_returns, get_valuation_rank, get_ranking). Even gives use case examples like 'NAV보다 비싸게 거래되는 ETF', '거래량 많은 ETF'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full responsibility for behavioral disclosure and does so well: it states that surge/plunge and volume_surge are based on '전일 대비' (previous-day comparison), that volume_surge is ordered by surge volume with a 5,000-share minimum, and that volume_renew means today's volume exceeds the max of the prior cycle. This significantly exceeds a minimal 'get movers' statement, though it omits output structure and any rate-limit or auth details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but each clause carries useful information, and the main purpose is front-loaded. It uses semicolon-separated enumerations and parenthetical annotations to pack signal definitions, market options, defaults, and comparative rules into a compact space. Slightly long, but every sentence earns its place given the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters, no output schema, and no annotations, the description is remarkably complete: it defines all eight signals, all market values, all relevant time windows, defaults, exceptions, and ordering/threshold behavior. The only omission is return-format details, but the absence of an output schema lowers the burden in that area, and the operational semantics are fully covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the schema already covers 100% of parameters with enums and Korean descriptions, the description adds substantial semantics beyond it: it clarifies that days is only used for new_high/new_low, cycle only for volume_renew, and it explains the comparative logic and thresholds for volume_surge. This is a strong enrichment over the schema, not mere repetition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource statement ('시장 특이 종목을 조회합니다') and enumerates all eight signal types (new_high, new_low, upper_limit, etc.) with Korean labels. This clearly defines the tool's scope and distinguishes it from broader sibling tools like get_ranking or get_vi_stocks by specifying exact signal semantics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance for parameter combinations: days only applies to new_high/new_low, cycle only applies to volume_renew, and it explicitly contrasts volume_renew ('longer-term volume breakout') with volume_surge ('previous day only'). However, it does not explicitly compare this tool with sibling market-scanning tools such as get_ranking or get_vi_stocks, so cross-tool guidance is implied rather than direct.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries the burden. It mentions performance (15-20 seconds) and clarifies that market is required, plus explains side=net bottom as net sell. Does not discuss data freshness or potential errors, but adequate for a data retrieval tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Description is informative but slightly verbose due to multiple alternative tool references and repeated mentions. However, it remains organized and each sentence adds value; no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema is provided, yet the description does not explain the return structure (e.g., list of stocks with net buy amounts). It mentions '순매수 상위' but lacks explicit field details. Given the tool is a ranking query, users might need to infer the output format. Performance note is helpful, but return format clarification would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Every parameter is described with enum values and Korean translations (e.g., subject: individual=개인, foreign=외국인). The market parameter includes additional context about query cost. Schema coverage is 100% and description adds meaningful context beyond the enum names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it ranks net buy by investor type and market, distinguishing from siblings like get_investor_trend and get_investor_rank by specific use cases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (searching stocks by investor type) and when not to use (already have a stock -> get_investor_trend; only foreign/institution -> get_investor_rank; real-time foreign -> get_foreign_intraday). Provides clear alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses non-obvious behaviors: `balance_rank` ignores certain parameters (and does so with a footnote), same-day data only becomes available after ~20:00 (otherwise empty results), and omitting `to_date` automatically falls back to the latest aggregation date. It does not mention auth or rate limits, but core invocation behaviors are well covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately long but well-structured: it leads with purpose, then explains each view, then covers parameter behavior and a timing caveat. It is dense and every sentence contributes value, but it could be slightly tightened without losing critical nuance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 5 optional parameters, no output schema, and no annotations, the description thoroughly covers purpose, usage, parameter interactions, and edge-case timing behavior. It clearly explains what trend fields are shown, but does not detail the return structure for `balance_rank`, which is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does 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 contextual value beyond the schema: it explains the `view` enum semantics, the default recent-30-day period, which parameters are ignored in `balance_rank`, and why omitting `to_date` is safer. This goes beyond the field-level descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description precisely states it queries stock lending (securities lending) information and distinguishes two views: `trend` (daily time series of contract/repayment/change and lending balance) and `balance_rank` (ranking of stocks by largest lending balance on a given day). It also clearly differentiates itself from sibling `get_short_selling` by cross-referencing it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use `balance_rank` ('which stocks have accumulated lending volume') vs `trend` for a single stock's flow. It also warns that `balance_rank` ignores `stock_code` and `from_date`, advises omitting `to_date` for safety due to late evening aggregation, and points to `get_short_selling` for combined short-selling flow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that it queries specific market data fields and the data source. It does not mention authorization, rate limits, or whether the operation is read-only, but the context implies it is a read query. Additional detail on return structure would improve transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently conveys the purpose, key data fields, and dependency on another tool. It is front-loaded and contains no extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the single required parameter and lack of output schema or annotations, the description provides sufficient context for correct usage. It explains what data is returned and how to obtain the input value, making the tool's functionality clear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes the parameter with a pattern and description. The description adds value by explicitly linking theme_code to the output of get_theme_groups, providing contextual meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves constituent stocks and market prices for a specific theme group, including specific fields like current price, change, change rate, volume, and period return. It also identifies the data source (kiwoom ka90002) and explains how to obtain the theme_code, which distinguishes it from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that theme_code must come from get_theme_groups, providing clear context for usage. However, it does not explicitly contrast with sibling tools or state when to use this tool versus alternatives like get_stock_price or get_stock_chart.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and discloses the most dangerous behavioral quirk: dates are settlement-based (D+2), so the latest 2 trading days' executions are absent, and pre-settlement ranges are unqueryable across all tools. This prevents false 'missing data' conclusions. Minor gap: no mention of return format or pagination, hence not a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Dense and front-loaded: purpose first, then defaults/params, then the critical D+2 warning and sibling routing. Bold formatting highlights the key trap. Slightly longer than strictly necessary due to re-emphasis of the settlement lag, but every clause carries differentiating information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, no output schema, and high sibling-confusion risk among ~50 tools, the description covers what it does, defaults, parameters, the critical behavioral quirk, and explicit exclusions. Missing only minor details like response shape and any date-range limits, which are predictable from the tool name and title.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds real value beyond the schema: default values (from_date = 30 days ago, to_date = today) and the semantic that date parameters are interpreted on a settlement basis, which materially changes how an agent should set them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource+scope: '계좌의 거래내역(매수/매도 등)을 기간별로 조회합니다' — retrieves account transaction history by period. The D+2 settlement disclosure and explicit contrast with get_order_executions and get_trading_journal clearly differentiate it from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit routing: same-day execution price/time → get_order_executions (with the caveat it has no past dates), same-day per-stock P&L → get_trading_journal, and states pre-settlement periods are queryable by NO tool. This tells the agent exactly when to use this tool vs alternatives and when to give up.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses that comparison/base is today's closing price (not previous day), and that sort, market, min_volume only affect ranking mode. No contradictions. Lacks details on rate limits or auth but adequate for a read-only tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single paragraph but well-structured: time frame, source, two modes, base price, ranking controls, sibling reference. No redundant sentences. Could split into bullet points for clarity, but currently concise enough.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description adequately covers return data: quote, 5-step order book, ranking. Explains all 5 parameters and their behavior in each mode. For a read-only tool with 5 params, it is complete and self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. Description adds significant meaning: explains stock_code toggles mode, clarifies sort options (up_rate, up_amount, etc.), market, min_volume. Provides context of KST time and source codes. Adds value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves after-hours single price trading info (16:00-18:00 KST). It distinguishes two modes: with stock_code returns quote and 5-step order book; without returns market-wide ranking. It differentiates from sibling get_orderbook for regular hours.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly specifies when to use (after-hours) and when not to (regular hours use get_orderbook). Explains the two different behaviors based on stock_code parameter presence, guiding the agent on when to provide or omit it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the default view (flow), what fields are included (closing price, change rate, volume, trading amount, net buys, program, credit ratio), and that session view shows pre/intra/after-hours distribution. It also references underlying API codes. It doesn't discuss rate limits or output format but provides substantial behavioral context beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but efficient; every sentence serves a purpose: stating the action, explaining the default view, framing when to use it, describing the alternate view, and listing alternatives. It's front-loaded with the core functionality and has zero fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, usage, both views, and alternatives thoroughly. It doesn't describe the output structure, but there's no output schema given, so this is a minor gap. It does mention '한 행에 묶어' (bundled in one row) giving some hint. For a complex tool with two distinct modes, this is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already covers 100% of parameters with descriptions, but the description enriches meaning by explaining the semantic difference between view=flow and view=session, clarifying the unit default (quantity), and giving practical context for count (default 20, max 60). This adds value beyond the schema's field descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves daily trading data for a stock in one call (종목의 일자별 거래를 한 번의 호출로 조회합니다). It names the two views (flow and session) and their content. It explicitly differentiates from sibling tools by pointing to get_stock_chart, get_investor_trend, and get_foreign_holding for other needs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance: '이 종목을 최근 누가 사고팔았나'를 볼 때 첫 번째로 쓰는 tool입니다 (first tool to use when checking who bought/sold). It also lists three alternative tools with their specific use cases, making the decision boundary clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It explains the metric, return content (trend data with moving averages for intraday), and data source. However, it does not explicitly state read-only nature or limitations like data freshness, but overall behavior is well-disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Concise 5-6 sentences with no fluff. Front-loaded purpose, then metric, then view options, then usage context and alternatives. Every sentence contributes value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 3 params with 100% schema coverage and no output schema, description covers metric, views, and alternatives adequately. Could mention return format briefly, but not essential for basic usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. Description adds value by explaining view options' specific behavior (daily: 60 trading days, intraday: 60 minutes with moving averages) and defaults. Enhances understanding beyond schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves execution strength trend (buy/sell volume ratio) for a stock, explains the metric and interpretation, and distinguishes from sibling tools (get_orderbook, get_investor_trend) with specific alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use (checking if buying pressure is increasing) and when not to use (orderbook or investor trends), including alternative tools. Also explains the two view options (daily vs intraday) with their specific time ranges and features.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses mode-specific content (daily includes institutional/individual net buying, ticks includes execution strength and best bid-ask), the only two listed instruments, default values, and the lack of a stock master. However, it does not describe the return format or mention any error conditions, which keeps it from being a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the purpose, followed by parameter explanations and a usage caveat. Every sentence earns its place with no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description covers the core behavior, parameter semantics, and usage boundaries well. It explains what daily and ticks modes return at a high level. The only minor gaps are the lack of explicit return shape and whether rows applies to both modes, but overall it is sufficiently complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds meaningful context by explaining the two instruments (1kg vs 100g mini), detailing what daily and ticks modes include, and explicitly clarifying that base_date is daily-only and that no stock code is needed. This goes beyond the schema's bare enum values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool queries KRX gold spot prices with a specific verb and resource. It distinguishes from siblings by explicitly directing gold ETFs/ETNs to get_stock_price and noting that search_stock cannot find gold spot instruments due to the absence of a stock master.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance: use for physical gold price (KRW per gram), and for gold ETFs/ETNs use get_stock_price instead. It also warns that stock codes cannot be entered and search_stock is not applicable, preventing common misuse.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It explains that the data is based on trading (매매 기준) and notes potential sign differences from get_foreign_holding, but it does not describe the output format or any side effects. Still, it effectively communicates the data semantics and default behaviors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense yet well-structured, using semicolons to separate ideas. Each sentence adds essential information without redundancy, making it efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of an output schema, the description does not explicitly state what the return data looks like, but it covers key contextual aspects like view-specific market support and differentiation from sibling tools. It is sufficiently complete for practical usage, though a mention of the output structure would improve it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by specifying which market values are valid for daily vs. streak views and clarifying that days applies only to streak. This goes beyond the schema's basic parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: querying stocks heavily bought/sold by foreigners and institutions, with explicit daily and streak views. It also distinguishes itself from related tools like get_foreign_holding and get_net_buy_rank, making its purpose 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/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool versus alternatives, such as using get_net_buy_rank for 12-entity selection and get_foreign_holding for holding-based criteria. It also clarifies the valid market options for each view, enabling correct selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full transparency burden. It discloses sorting, first-page-only behavior, the 100-stock limit, and the ambiguity error behavior. It stops short of specifying the returning data shape or authentication/rate constraints, so it is strong but not maximal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one packed paragraph but has almost no filler: the first sentence states the main purpose, the second covers ordering and pagination, and the final sentence handles disambiguation and alternative tools. Every sentence provides actionable value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For tool selection, the description is complete enough: it tells the agent what to pass, how to resolve the only meaningful input ambiguity, and what behavior to expect. It does not declare the exact return fields in the absence of an output schema, which keeps it from scoring a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers both parameters well (100% coverage), so this is above baseline. The description adds extra semantic context such as that sector_code can be either a 3-digit industry code or an industry name, cannot be a theme name, and that ambiguous names will produce an error. This improves over raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool '조회' retrieves quotes for stocks belonging to a specific KRX sector, identifies the underlying operation (ka20002), and even differentiates from theme-based lookups by stating theme names are not accepted. This unmistakably distinguishes it from get_theme_stocks and other sector-related siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit routing guidance: if the user asked about '테마', use get_theme_groups then get_theme_stocks; otherwise get_sector_stocks is applicable. It also defines that sector_code can be obtained from get_market_index, and warns about overlapping names like '반도체'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses key behavioral traits: it can only sort by one criterion at a time, cannot combine indicators, and must be called multiple times for combined filters. It also mentions the underlying API code (키움 ka10026) and confirms this is the only valuation scanning tool. Though it doesn't describe the return format, the read-only nature is clearly implied.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficient: four sentences, each serving a distinct purpose—core function, limitation/workaround, usage patterns, and differentiation from alternatives. No fluff or redundant repetition of schema details. Well-structured and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema and no annotations, the description covers purpose, usage, limitations, and alternatives thoroughly. It falls short of describing the output structure (e.g., what fields the returned list contains), but for a straightforward query tool this is a minor gap. The guidance on when to use which metric and the combination workaround makes it robust for agent decision-making.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (both top and metric have descriptions). The description adds value beyond the schema by explaining the strategic meaning of each metric (low PER/PBR for value, high ROE for efficiency, high PBR/low ROE for overheating) and the top parameter's default and max are already in the schema. This semantic guidance helps the agent choose appropriate metrics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool sorts the entire market by one of PER/PBR/ROE and returns the top 100 stocks (e.g., '시장 전체를 PER·PBR·ROE 중 한 가지 기준으로 줄 세운 상위 100종목을 조회합니다'). It uses specific verbs and resources, and explicitly differentiates from get_ranking and get_stock_price by noting this is the only tool for market-wide valuation scanning.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage context: when to use this tool (value screening with low PER/PBR, capital efficiency with high ROE, overheating/insolvency checks with high PBR/low ROE), and when not to use it (volume/price-change rankings → get_ranking, single-stock PER/PBR → get_stock_price). Also explains the limitation of not combining metrics and the workaround of calling twice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description declares the tool is read-only (읽기 전용) and mentions the API endpoint ka01300, which adds transparency. It states that group editing is not supported, which is a behavioral limitation. No annotations were provided, so the description carries the burden. It does not discuss error conditions or rate limits, but for a simple parameterless read operation, this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the main purpose. It includes an alternative tool reference and a limitation. Every sentence earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and no output schema, the description covers the core functionality. It mentions the output fields (group code + group name) and the API code. It could mention more about the output format or potential empty results, but it is sufficiently complete for a simple list retrieval tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameters, so schema coverage is 100%. The description adds meaning by stating what is retrieved (group code + group name). No parameters need explanation, so a baseline of 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a list of watchlist groups (group code + group name) stored in the HTS. It uses the verb '조회합니다' (inquiry) and specifies the resource. It distinguishes itself from the sibling tool get_watchlist by noting that get_watchlist is for specific group items.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to use get_watchlist for specific group items, and states that group editing (add/delete) is not supported by the API, so only inquiry is possible. This provides clear when-to-use and when-not-to-use guidance, with an alternative named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It goes beyond a simple read-only expectation by detailing that empty results are a normal state during non-calculation times and not an error. This is valuable contextual information that helps the agent correctly interpret responses.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description uses three sentences, each earning its place: the first states the core function, the second explains the concept and optimal usage timing, and the third covers empty-result behavior and alternative tools. It is compact and well-structured without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only ranking tool without an output schema, the description sufficiently covers necessary context. It explains the special timing contexts, empty-result behavior, and points to sibling tools for related but distinct queries. Given the tool's simplicity and the rich schema, no further explanation is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All three parameters (top, sort, market) have descriptions within the input schema, giving 100% schema description coverage. The tool description itself adds no parameter-specific semantics beyond what the schema already provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: '예상체결가 기준 순위를 조회합니다' (queries ranking based on expected execution price). It explicitly names the underlying source (키움 ka10029) and distinguishes itself from sibling tools by mentioning specific alternatives like get_ranking and get_after_hours.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly explains when the tool is useful (during simultaneous auction phases before open and close), warns when results will be empty (outside Kiwoom's calculated times), and names three alternative tools for different use cases (get_ranking, get_market_movers, get_after_hours). This provides clear 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.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does so thoroughly. It discloses that the date range is determined by Kiwoom, that there is no date parameter, that observed behavior shows 6-day-old executions return zero rows, and that settlement is D+2. It also states the tool is read-only and does not execute orders.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every clause earns its place, and the most important constraint — recent-only, no past dates — is front-loaded. The bolded warnings and alternative routing are structured so an agent can quickly extract the critical behavioral rule before reading supporting details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema and no annotations, the description is remarkably complete: it covers the returned fields, the filtering parameters, the date-range limitation, settlement timing, sibling alternatives, and the read-only nature. Nothing an agent needs to decide whether to call this tool is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all three parameters. The description adds that stock_code, side, and order_no can narrow the results, but this is already implied by the schema and adds no new semantic detail beyond grouping the filters together.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: it retrieves the account's recent execution history, explicitly clarifying that past-date executions are not included. It also distinguishes itself from get_transactions, get_pending_orders, and get_trading_journal, so an agent can tell them apart without opening schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use and when-not-to-use guidance: it says not to call this tool for past dates like 'yesterday's execution price', and directs the agent to get_transactions after settlement. It also names get_pending_orders for unfilled orders and get_trading_journal for daily per-stock aggregation, leaving no ambiguity about alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the underlying Kiwoom API calls (kt00001, kt00018, kt00004, kt00008) and explains how settlement view breaks down summary estimates. It does not mention rate limits or authentication, but for a read-only account query, the disclosed behavior is sufficiently transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence serves a purpose: it defines the default view, lists its contents, explains the settlement view with a rationale, and names alternative tools. Content is front-loaded with the default view first, and the structure is logical and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema), the description fully covers the possible return content for both views and provides context for when to use sibling tools. It is complete and self-contained, leaving no major gaps for an AI agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema coverage is 100%, the description adds substantial semantic depth beyond the schema by detailing exactly what each view includes (e.g., 예수금, 총평가금액, 손익, D+1/D+2 estimates, fees, taxes). This exceeds the baseline for high schema coverage and significantly enhances parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that this tool retrieves account balance data with two views: summary (예수금, 평가금액, 손익 등) and settlement (다음 결제일의 건별 명세). It uses specific verbs and enumerates the exact contents, distinguishing it from sibling tools like get_transactions and get_account_holdings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly explains when to use each view (summary for overall balance/profit-loss, settlement for upcoming settlement details) and explicitly directs users to get_transactions for past settlement history and get_account_holdings for per-stock balances, providing clear alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries the burden and does so richly: it explains the two modes (stock_code present vs absent), the different return shapes for each view (top 5 brokers, cumulative 50-broker ranking, dropped brokers with times), the 🌐 flag for foreign brokers, and how direction/days parameters affect the result. It also explicitly warns that the data is broker-based, not investor-based, preventing misuse. This is thorough behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense paragraph, but every sentence adds value. It front-loads the core purpose and uses formatting (bold, line breaks implied) to highlight key terms. It could be better structured with bullet points for the three views, but given the complexity of the behavior, the length is justified and there is no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (two modes, multiple views, optional parameters), the description covers the most important behavior and result types. It doesn't list exact output fields (e.g., whether it returns arrays of objects with specific fields), but the absence of an output schema means the description should compensate; it does so sufficiently for an agent to understand what data to expect, though more detail on the return structure would make it fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the schema documents all parameters with descriptions (100% coverage), the description adds crucial semantic context beyond them: stock_code presence switches the entire result mode, top means different things depending on view (number of stocks vs number of brokers), direction has different defaults/effects in market-wide vs broker_rank modes, and days only applies to market-wide mode. This adds meaning that the schema alone does not convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description precisely states the tool's purpose: querying securities firm window trading trends ('증권사 창구별 매매 동향을 조회합니다'), and immediately differentiates it from investor-trend tools by emphasizing '창구 기준' (broker-based). It also distinguishes between the two modes (with/without stock_code) and mentions specific view types (top5, broker_rank, dropout), making it clear what the tool does and how it differs from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is provided: use view=top5 for daily top 5, broker_rank for cumulative ranking across all 50 brokers, dropout for brokers that fell off the top. It also explains when to omit stock_code for market-wide foreign broker rankings, and even names alternatives (get_investor_trend, get_foreign_intraday) for foreign net buying by investor type, plus the key distinction that this tool is broker-based. This is exemplary usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so well: it discloses the default ordering (등락률 상위), the stock_code filtering behavior, that limit is ignored during stock search, the absence of a theme-name parameter, and the theme/sector naming ambiguity. This goes well beyond a minimal read-only description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but well-front-loaded with the core action and returned fields. It earns most of its length through important caveats, though there is slight redundancy: the 'default is top 등락률' idea appears twice. Overall, it is appropriately sized for the disambiguation burden.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 2-parameter read-only list tool with no output schema and no annotations, this description is highly complete. It explains what the tool returns, default behavior, parameter interactions, the missing theme-name lookup path, and how to choose between sibling tools. An agent has enough to invoke it correctly in most realistic scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds practical meaning beyond the schema, such as 'if the theme you want is not in the default 30, raise limit to 100' and clarifies that stock_code searches themes containing that stock. Most parameter semantics come from the schema, with a small boost from the added usage guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: '키움 테마 그룹 목록을 조회합니다' and lists the returned fields. It explicitly differentiates from sibling tools, especially get_sector_stocks (KRX sector classification) and get_theme_stocks (constituents), so an agent can select it correctly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit when-to-use guidance: use this when the user says '테마', use get_sector_stocks for 업종, and use get_theme_stocks for constituents of a specific theme. It also warns there is no theme-name filter and advises raising limit to 100 if the desired theme is not in the default top 30.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses read-only behavior and data augmentation from master (trading halt, management stocks). Could mention output format or pagination but sufficient given no 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/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with main action and source, efficient and informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a single-parameter read tool with no output schema; covers prerequisite and return data content.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Single parameter 'group' with clear description, examples ('000', 'etf'), and hint to use sibling tool. Schema coverage is 100% and description adds extra context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it retrieves the list of stocks in a watchlist group, specifies source and read-only nature, and distinguishes from sibling tool get_watchlist_groups by indicating its use for finding group.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells how to pass group code or name, advises to use get_watchlist_groups if group unknown, and describes the augmented data (name, previous close, market, caution status).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- 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/5Is 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/5Given 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/5Does 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/5Does 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/5Does 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.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses both operational modes, the output fields (close, volume, foreign net change, owned shares, ratio, limit exhaustion), and the important caveat that the data source differs from investor-trade tools and signs may be reversed. This goes well beyond a basic statement of function.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise despite covering two modes and ranking subtypes. It front-loads the primary purpose, uses bold for key distinctions, and each sentence adds essential information without fluff. It is appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 optional parameters, two modes, no output schema or annotations), the description covers the main use cases, mode selection, and data source caveats. It doesn't specify the exact ranking output format (e.g., whether it includes stock names/codes), but the description is sufficiently complete for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and parameter descriptions are already detailed, but the description adds critical semantic context: how stock_code and rank interact, which day values apply to which rank mode (limit_surge: 1/5/10/20; period_net: 1/3/5/10/20/60/120; streak: fixed 3 days), and that market/direction apply only in rank mode. This meaningfully exceeds what the schema alone provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool queries foreign ownership/limit trends with two distinct modes: per-stock daily trend and market-wide rankings. The description distinguishes it from sibling tools (get_net_buy_rank, get_investor_trend, get_foreign_intraday) by noting the different data source, so it's specific and well-differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly explains when to use stock_code (per-stock trend) vs rank (market-wide rankings) and details each rank type (limit_surge, period_net, streak) with their specific criteria. It also states the tool should be used for foreign ownership/limit data and not as a substitute for investor-trade-based tools, providing explicit exclusions and alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and excels: it clarifies that the order book represents pending orders, not executions, which prevents a common misinterpretation. It also specifies the 10-level depth, the KRX+NXT integrated scope, and the source message ID (ka10007), providing rich behavioral context beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three dense sentences with no filler. The core functionality is front-loaded, and every sentence earns its place: what it returns, when to use it, and which alternatives to consider. It is concise yet highly informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter tool, the description covers the returned content (10 levels, quantities), the integrated market scope, the intended use case, and differentiates from all relevant siblings. No output schema is needed because the description adequately explains what the agent should expect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% coverage with a pattern and example for stock_code, so baseline is 3. The description adds practical guidance by telling the agent to use search_stock to find the code first, thereby adding value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('조회합니다') and names the exact resource: 10-level bid/ask prices and quantities on an integrated KRX+NXT basis. It also distinguishes itself from related tools like get_execution_strength, get_order_executions, and get_stock_quotes, making its purpose uniquely clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use the tool (to see waiting volume at each price and whether bid/ask side is thicker) and explicitly directs to alternatives for execution strength, account executions, and multiple current prices. It also advises using search_stock if the code is unknown, giving complete usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so excellently. It discloses that date_rank allows past dates with extra fields, stock_intraday only provides the most recent trading day and ignores base_date, amounts are in million won, and market has no 'all' option. It also notes arbitrage_balance represents unclosed positions, not trades, which is critical behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but every clause carries unique information—view definitions, constraints, units, and exceptions. It is front-loaded with the primary purpose and logically organized from view enumeration to parameter applicability. There is no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Without an output schema, the description indicates key output dimensions for several views (e.g., date_rank includes amount and trade weight; stock_intraday includes quantity) and sets expectations about accuracy and date limitations. However, views like market_daily and market_intraday are only described as '추이' without specifying output fields, leaving a slight gap for a complex multi-view tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. However, the description adds significant inter-parameter constraints: 'direction은 top·date_rank에, unit은 view=top에만, market은 top·date_rank·market_daily·market_intraday에만 적용됩니다 (종목 단위 view와 arbitrage_balance에는 적용되지 않습니다).' This goes beyond per-parameter schema definitions and clarifies combinations, which is highly valuable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with '프로그램 매매 상위 종목과 추이를 조회합니다', clearly stating the tool retrieves program trading top stocks and trends. It then enumerates seven distinct views, differentiating the resource and scope. This is specific and distinguishes it from sibling tools like get_institution_trend or get_foreign_intraday.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use guidance: '한 종목의 프로그램 수급이 장중 언제 뒤집혔는지를 보려면 stock_intraday, 날짜별 흐름은 stock_daily입니다.' It also clarifies accuracy trade-offs ('당일 순위는 top이 서버 집계라 더 정확합니다') and parameter applicability exclusions. This is exemplary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the transparency burden. It discloses that values are provisional in 1,000-share units, may differ from final values after market close, and can even have reversed signs. It also explains why certain investor types are not queryable, adding critical behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, followed by usage guidance, caveats, and alternatives. Every segment earns its place, using bold and em-dashes to emphasize key points without redundancy. Despite its length, it remains efficient for the complexity involved.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (5 parameters, 4 enums, no output schema), the description is complete enough for correct invocation. It covers the real-time scope, investor limitations, provisional value behavior, and explicit tool alternatives, ensuring an agent can decide when to use it and what to expect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema coverage is 100%, the description adds significant meaning beyond the schema: it clarifies that the unit parameter is only valid for the foreign investor, that the market parameter results in server-side sorting, and that investors like individuals and financial investment are not supported. These details are not present in the schema property descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool extracts stocks that a specific investor is currently buying during regular market hours ('어떤 주체가 지금 사고 있는 종목') and identifies the resource ('전 종목에서'). It also distinguishes from siblings by explicitly mentioning alternatives (get_net_buy_rank for settled days, get_investor_trend for specific stocks).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit usage guidance: '실시간 수급을 볼 때 쓰세요' (use when viewing real-time supply/demand), and clearly contrasts with post-market and single-stock alternatives. It also states the exchange limitation: individual and financial investment investor types are unavailable during market hours.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GitHub Badge
Glama performs regular codebase and documentation scans to:
- Confirm that the MCP server is working as expected.
- Confirm that there are no obvious security issues.
- Evaluate tool definition quality.
Our badge communicates server capabilities, safety, and installation instructions.
Card Badge
Copy to your README.md:
Score Badge
Copy to your README.md:
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
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