거래원 동향 조회

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.

Is 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.

Given 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.

Does 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.

Does 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.

Does 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.