Fiscal years of a company

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

Annotations already declare read-only, idempotent, non-destructive, open-world, so the safety profile is covered. The description adds value beyond that: result ordering (newest first), calendar convention (Jalali), and the meaning of an empty result. It stops short of describing the exact return shape (array of strings vs objects), which matters somewhat since there is no output schema.

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 tight sentences: the first states what is returned and how it is ordered; the second gives the downstream use and the failure diagnostic. No filler, and the core capability is front-loaded.

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 one-parameter read tool with no output schema, the description covers purpose, ordering, calendar, downstream use, and the empty-result case — enough to call it correctly. The only omission is the concrete return shape (what each element looks like), which the absence of an output schema leaves slightly underspecified.

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% for the single `symbol` parameter, so baseline 3 applies. The description reinforces the required input indirectly ("for one company", wrong symbol ⇒ empty list) and points at cd_company for validating the symbol, but adds no format rules beyond what the schema already states.

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?

"List the fiscal year-end dates codal.ir knows for one company, newest first (Jalali)" names a specific verb (list), a specific resource (fiscal year-end dates for one company), plus ordering and calendar. It is instantly distinguishable from siblings like cd_search_letters and cd_company, which are named as different steps.

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?

Explicit workflow guidance: call this before cd_search_letters and pass from_date after the year end with period_months 12. It also gives an exclusion/failure rule — an empty list usually means a wrong symbol, check with cd_company — covering both when to use it and what to do when it fails.

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