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.