HOLD! Korea Stock Ownership & Insider Trades

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

Goes well beyond the readOnlyHint/openWorldHint annotations: it discloses the computation methodology (weighted average for buys, quantity-only reduction for sells, split/merge adjustment) and a data-quality taxonomy (reported/partial/unavailable) with legal reasons for missing prices. It also warns the agent not to assert an average price when basis is partial, which is genuinely actionable 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.

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

Front-loaded with the core purpose, then methodology, then parameters, then return fields and caveats — a logical order with no filler. It is dense and the middle sentences run long, but each clause carries necessary information.

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

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

There is no output schema, and the description compensates fully by enumerating the returned fields (avg_cost, held_shares, priced_shares, coverage_pct, buys, first_trade, last_trade) and explaining the basis semantics. For a two-parameter analytics tool, nothing an agent needs to call or interpret it is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: holder is a partial reporter name whose omission changes behavior to 'all holders with prices', and ticker selects a single stock. That is more than the schema's bare field descriptions provide.

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?

States a precise verb and resource: computes a per-holder average purchase price for one stock, and describes the exact data source (5% large-holding report detailed change tables). An agent can immediately distinguish this from sibling tools like get_holders or get_holder_history.

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?

Explicitly states the scope rule (pass holder for one holder, omit for all priced holders) and an exclusions rule (executive/major-shareholder reports have no price and are not used). It does not name a sibling tool as an alternative when this data is unavailable, which keeps it below a 5.

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

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

The annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds a genuinely useful data-availability caveat: members and trades exist only for 5% bulk-holding reports received in original text. It says nothing about failure modes or missing filings, which keeps it at 4.

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 front-loaded with the core purpose, then the input, then the return sections, and every clause carries information. The field enumeration is dense but justified given there is no output schema.

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?

With no output schema, the description carries the burden of explaining return values, and it does so by naming each section and its fields. It also flags the conditional presence of members and trades, so an agent knows what to expect before calling.

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

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

Schema coverage is 100% and the single parameter is already documented as source_url or a 14-digit rcept_no. The description restates that and adds only the hint that the value typically comes from another tool's output, which is marginal added meaning.

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 a specific verb and resource ('공시 한 건의 세부 내역') and then enumerates the three result sections (reports, members, trades) with their contents, which clearly separates it from the list-oriented siblings such as get_holders and get_recent_changes.

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?

It gives a concrete use case ('어떤 거래로 지분이 바뀌었는지, 매수인지 출자전환인지 확인할 때') and explains how to obtain the input from other tools' source_url or rcept_no. It does not name an alternative tool or state when not to use it, 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.

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered; the description adds substantial unstated context: unlimited time range, newest-first ordering, the fact that trade_date appears only for filings received in original-text form, and that trade_price is the average acquisition price of that report. It does not address result volume or pagination behavior (limit defaults to 50 only in the schema), which keeps it below 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.

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

Front-loaded with purpose and scope, then alternatives, then field semantics in short declarative clauses. Dense but every sentence carries information an agent would otherwise have to guess, and there is no filler.

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?

With no output schema, the description correctly takes on the burden of explaining return-field semantics (change_type values, non_trade, trade_date, trade_price) and even flags the listing and insider-new edge cases that would otherwise cause misreads. The remaining gap is operational: nothing about result size, limit interaction, or what an empty result means.

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

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

Schema coverage is 67% and the description fills a real gap: it specifies that holder accepts a partial reporter name (the schema has no description for holder at all) and clarifies that ticker is mandatory with no date bound. from/to and limit are left to the schema, so it improves on the baseline without fully compensating.

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 a specific verb and resource ('지분 변동 공시 전체 이력') and pins the scope: one ticker, both 대량보유 and 임원·주요주주 reports, newest first, no period restriction. It also names the sibling it is not (get_recent_changes) so an agent can distinguish them without opening either schema.

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

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

The intended question ('이 회사 지분이 언제 어떻게 바뀌었나') is stated explicitly, alongside an explicit alternative for multi-ticker recent scanning (get_recent_changes) and a hand-off to get_filing for per-transaction detail via source_url. Both the when-to-use and the when-to-use-something-else are covered.

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

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

Annotations already establish readOnlyHint=true and openWorldHint=false, so the safety profile is covered; the description adds substantive data-scope behavior instead. It discloses the recency cutoff (2 years), the 1% minimum, the exclusion of foreign and minority-shareholder aggregates, and that each row carries as_of and source_url. It does not address error behavior or empty-result handling, so it is strong but not exhaustive.

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 core resource and aggregation rule are front-loaded, followed by data-coverage caveats and per-row fields, with no filler sentences. Density is high but each sentence contributes scope or output information. The mid-sentence source=major/insider clause is the one spot that reads ambiguously against a schema with only ticker.

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?

With no output schema, the description must convey return shape, and it does: holder-level rows with ownership ratio, as_of, and source_url. Combined with the exclusion rules, an agent knows what will and will not appear. Remaining gaps are edge cases (empty results, ticker ambiguity) rather than core behavior.

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

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

There is a single required parameter (ticker), and schema description coverage is 100% (ticker code or exact name), so the schema already carries the semantics. The description adds nothing about ticker resolution behavior and instead discusses source names that are not parameters, so the baseline of 3 applies.

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 a specific verb+resource: major holders and their ownership percentages for a stock, with special related parties aggregated. It clearly bounds what counts as a holder (5% bulk-holding reports, insiders incl. 10%+ shareholders, 1%+ threshold). It does not explicitly distinguish itself from siblings like get_holder_history or search_holder, which keeps it from a 5.

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?

Usage is implied through scope statements (latest disclosure per holder, holders without reports in the last 2 years excluded, no foreign/minority totals), which signals when results will be thin. However, there is no explicit when-to-use/when-not guidance and no named alternative such as get_holder_history for time-series needs. The mention of source=major/insider is not a selectable parameter here, which adds mild ambiguity about how to choose coverage.

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

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

Annotations already declare a safe, closed read (readOnlyHint true, openWorldHint false), and the description adds behaviour the annotations do not: results are restricted to stocks with 5% large-holding or 1%+ executive/major-shareholder filings and are sorted by ratio descending. It also explains that value is disclosed share count times the latest close price, total_value is the sum, and that total above shown means raising limit will return more — useful detail beyond structured fields, though unit/currency of the ratio and update freshness are unstated.

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 front-loaded with what the tool returns and the reporting filter, then moves to parameter caveats, then to output semantics. Every sentence carries information; density is high but nothing is filler, and the caveat about partial names is placed where it matters.

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?

There is no output schema, so explaining value/total_value/total-versus-shown in the description is exactly the right compensation, and the reporting-threshold caveat prevents over-reading the list as complete ownership. Only min_ratio's meaning and the treatment of include_indirect's effect on ratios are left to inference.

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

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

Schema coverage is 80%, so the baseline is 3, but the description adds real meaning: it identifies entity_id as coming from search_holder and scopes it to a single holder, and explains the ambiguity risk of the holder name parameter and the limit/total interplay. Only min_ratio is left unexplained in both schema and description.

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 opening sentence names a specific verb and resource (the list of stocks held by a holder, with ownership ratios, sorted by ratio descending) and states the reporting threshold that limits which stocks qualify. It is clearly distinguishable from the holder-listing or history siblings, though it never names those siblings explicitly.

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?

It states the default holder (국민연금) and recommends passing entity_id from search_holder, warning that a partial 'holder' name can mix in other same-named holders and unconfirmed reports. That is concrete when-to-use and when-to-prefer-an-alternative guidance, though it does not say when to use a sibling such as get_holders instead.

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

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

Annotations already establish a read-only, closed-world read, so the description's job is data semantics — and it delivers: default 50 rows with a limit knob, and the important warning that rows with change=listing or non_trade=true are not market trades and must be excluded from trade totals. It does not cover pagination beyond limit or ordering stability, which 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.

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

Front-loaded with the resource and timeframe, then filters, then the sibling alternative, then caveats — a sensible priority order with no filler. It is dense to the point of being crowded, packing five distinct ideas into one paragraph, but every sentence carries information.

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

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

With no output schema, the description correctly spends its words on returned-field semantics — the meaning of change values and the kind taxonomy (buy, placement, control, non_trade, unknown) for 5% filings. An agent could call it and interpret results correctly; only the full field list and result-count/pagination behavior are left unstated.

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

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

Schema coverage is 80%, so the schema already documents days, limit, ticker and entity_id defaults. The description largely restates those defaults, adding only that holder and entity_id act as owner-level filters (implying they compose with ticker). That is a small increment over the schema, consistent with the baseline 3 for well-covered schemas.

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?

States a specific verb and resource: a feed of ownership-change filings from the last N days, newest first, and frames its scope as cross-ticker ('who bought and sold this week'). That scope statement is exactly what separates it from the single-entity siblings, so an agent can pick it without opening any schema.

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?

Explicitly names when to use it (cross-ticker weekly activity), how to narrow it (ticker for one symbol, holder/entity_id for one owner), and names the alternative with its condition — use get_holder_history when the full history of a single ticker without a date limit is needed. When-not guidance is present, not merely implied.

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

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

Annotations only say readOnly and closed-world; the description goes well beyond them by explaining that duplicate names produce separate rows, defining each result field's meaning, and disclosing the null-entity_id edge case (unconfirmed report bundles only lookupable by name). That null case is exactly the kind of behavioral trap the description must surface, and it does.

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?

Front-loaded with the action, then result fields, then downstream usage — a logical order with no filler sentences. It is a single dense block mixing three concerns, so it is slightly hard to scan, but every clause carries information.

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

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

With no output schema, the description must explain the return shape and it does, field by field, plus the downstream identifier contract and the null-entity_id caveat. For a one-parameter search tool that is the complete set of things an agent needs to call it and act on its output.

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

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

Schema coverage is 0% for the single `query` param, so the description must carry it; it does by clarifying the param is a person/company name and that Korean spellings are accepted and resolved to English filer names. It adds no info on partial matching, minimum length, or ambiguity handling, so it compensates but not exhaustively.

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?

Names a concrete verb (find) and resource (holder: institution / asset manager / individual) and scopes it to name-based lookup, which separates it from the sibling ID/history tools. It also previews the returned shape (kind, role, key_hint, top, corps), so an agent knows exactly what kind of result to expect.

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?

Explicitly states the input condition (search by name, Korean input resolved to English filer names) and, critically, tells the agent to chain the returned entity_id into get_portfolio / get_recent_changes / get_holder_history. It does not contrast itself with search_symbol or explain what to do when a name yields many rows, so it stops short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds a real behavioral constraint beyond that — only *currently listed* Korean stocks are searched and matching is by partial string. It says nothing about multiple matches (list vs. single best hit), result limits, or ordering, which matters for a lookup tool feeding other calls.

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

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

Two short sentences, front-loaded with what it does and followed by why you'd call it. No filler, though the second sentence could be folded into the first without loss.

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?

There is no output schema, so the description is the only place to learn what comes back — and it never says whether the response is a list of matches, a single ticker, or includes names/codes together. For a one-parameter lookup tool this is a notable omission, though the core contract is still usable.

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

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

Schema coverage is 0% and the single 'query' property is an untyped-in-practice bare string, so the description must carry the load. It does add meaning by saying both a partial stock name and a stock code are acceptable inputs, but it gives no detail on format (e.g., 6-digit code vs. full name) or ambiguity handling.

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 gives a specific verb ('찾는다' / find) and resource ('지금 상장된 한국 종목' / currently listed Korean stocks), plus the matching keys (partial name or code). That is enough to distinguish it from siblings like search_holder or get_holders, though it never names a sibling explicitly to confirm the contrast.

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?

It states the operational context clearly: the result is meant to supply the ticker argument for other tools, which tells an agent when to reach for it. It does not state any when-not conditions or name an alternative for resolving tickers another way.

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