투자자 주체별 순매수 상위 (시장 전체)

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

No annotations are present, so the description carries the full burden. It discloses that figures are based on the last completed trading day and contrasts real-time alternatives, adding valuable temporal context beyond the schema. The performance caveat (15-20 seconds) is already covered in the schema's market parameter, so this is sufficient, though edge cases or error states are not mentioned.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is information-dense yet concise, with bolded key phrases and a logical flow: verb+resource, usage examples, alternative tools, and data timing. Every sentence provides actionable guidance; no redundancy or fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 6-parameter tool with 5 enums and no output schema, the description provides complete context: what it does, when to use, when not to use, data freshness, and real-time alternatives. It fully complements the schema and sibling tools, leaving no major gaps for correct selection and invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, providing a baseline of 3. The description adds value by giving example usages that convey parameter combinations (e.g., '사모펀드가 산 코스닥 종목' implies subject=private_fund, market=kosdaq, side=buy), and clarifies that side=net with direction=bottom gives net sell. This enriches the schema's meaning without being redundant.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states the tool scans all market stocks and extracts the top net buy/sell by investor subject, using a specific verb ('뽑습니다') and resource (키움 ka10066). It clearly distinguishes from sibling tools by naming get_investor_trend and get_investor_rank as alternatives, and lists the 12 selectable subjects.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit when-to-use guidance with concrete examples ('연기금이 어제 뭘 담았나', '투신 순매도 상위'). It names exact alternatives for different scenarios: get_investor_trend for a single stock, get_investor_rank for quick foreign/institution view, and get_foreign_intraday for real-time foreign-only. Also specifies data is as of the last completed trading day, clarifying the non-real-time nature.

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