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

Annotations already declare readOnlyHint=true, and the description adds behavior beyond that: it returns 'announcement details, not just a price-adjustment factor', returns 'CSV, one row per action', and if the symbol is ambiguous, 'returns JSON candidates instead'. This clarifies return format and edge-case behavior without contradicting the annotations.

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 compact and front-loaded: purpose, sibling distinction, then usage guidance, then return format and edge case. Every sentence contributes new information; there is no filler or redundancy.

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?

For a read-only list tool with no output schema, the description covers return format (CSV, one row per action), ordering (oldest first), ambiguity handling (JSON candidates), and date-range semantics. Combined with the detailed input schema and annotations, the agent has everything needed to use the tool correctly.

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% (every parameter is described in the schema). The description adds extra practical meaning: e.g., 'pass from=<today> to jump straight to upcoming ones, which is the most common need' and 'matches every one of its share classes, not just one' for symbol, which go slightly beyond the schema text to help the agent choose values correctly.

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 a calendar of corporate actions (dividends, rights issues, share splits)'. It explicitly names the types of actions and contrasts itself with the sibling get_announcements ('for other company disclosures... use get_announcements instead'), so the agent can immediately tell which tool fits the task.

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 explicit when-to-use vs alternative guidance: 'This is the tool for dividends/rights/splits specifically; for other company disclosures... use get_announcements instead.' It also provides concrete usage patterns: omit all filters to browse everything, pass from=<today> for upcoming actions, optionally scope to a company or kind. This leaves no ambiguity about when or how to invoke it.

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