stock_dividends

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

No annotations are supplied, so the description has to carry the full behavioral burden. It does disclose the data source and scope (TWSE/TPEx) and that the results are limited to the near term, which is useful context. However, it is silent on what happens when query is omitted, what the returned record contains, freshness or caching, and error or empty-result behavior.

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?

It is short and front-loaded, leading with the scope, then giving the filter, and it keeps the essential information visible. The cost is that the Chinese and English halves duplicate the same content rather than complementing each other, which makes it more verbose than it needs to be.

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?

It is a simple tool with one optional parameter, so the description is nearly sufficient. It does, however, fall short on two points that matter for calling it correctly: there is no output schema, and the description does not describe the shape of the returned ex-dividend records or the default result when no query is supplied.

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 bare 'query: string' property would be otherwise meaningless; the description compensates by explaining that it accepts either a stock code or a stock name and that it is optional. The one remaining gap is that the description never states what the unfiltered default result is.

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: upcoming ex-dividend and ex-right dates for Taiwan TWSE/TPEx listed and OTC stocks, with an optional code or name filter. That is clearly distinct from siblings like stock_quote or stock_market_summary, though it never names or excludes those alternatives 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?

Usage is implied rather than stated: the optional query parameter signals that callers can narrow the results to one stock. There is no explicit guidance on when the results should be read as an unfiltered calendar, nor any exclusion pointing to a sibling tool for historical dividend data or quotes.

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