get_shareholder_return_disclosures

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

No annotations are present, so the prose carries the full burden of behavioral disclosure. The description usefully clarifies that the date range applies to filing dates and that this is a fetch from external DART endpoints, but it does not mention API-key requirements, rate limits, pagination, or empty-result behavior. These are meaningful gaps for an external 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.

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

The description is well-structured: purpose first, endpoint context second, then a clean Args block. The disclosure-type list is long but necessary because the schema provides no enum values, and every line carries useful information without 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?

Given that an output schema exists, return-value documentation is handled separately. The description fully documents all four inputs, the date semantics, and the available disclosure types. It is only missing operational details such as DART API-key prerequisites and behavior when no disclosures are found, so a perfect completeness score is not warranted.

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 0%, so the parameter documentation in the description is essential and fully compensates. It defines corp_code with format and a concrete example, start_date and end_date with accepted formats and examples, and disclosure_type with all valid values, Korean labels, and the default. An agent can construct a correct call from this text alone.

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 opens with a specific verb and resource: 'Get shareholder-return-related disclosure decisions over a date range.' It then enumerates exactly what it fetches (capital increases, capital reductions, treasury stock activity), which makes the tool readily distinguishable from siblings like get_dividend_info or get_financial_statements.

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 description conveys a clear usage context: fetching board disclosure decisions from Open DART major-matters reports within a filing-date range, with a defined set of disclosure types. It does not explicitly name sibling alternatives or state when not to use this tool, so it stops 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.