Skip to main content
Glama
codal-mcp

codal-mcp

by sepehr071

Fiscal years of a company

cd_financial_years
Read-onlyIdempotent

Lists a company's known Jalali fiscal year-end dates, newest first, so you can verify annual statement periods before searching Codal filings.

Instructions

List the fiscal year-end dates codal.ir knows for one company, newest first (Jalali).

Use it before searching annual statements with cd_search_letters (period_months 12). An empty list usually means a wrong symbol: check cd_company.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "symbol": "<symbol>"
    },
    "name": "cd_financial_years"
  }
}

Input Schema

NameRequiredDescriptionDefault
symbolYesExact Persian trading symbol, e.g. فولاد.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.2.0
    • changedInput schema / properties / symbol / description
      Previous value: -"Exact trading symbol in Persian, e.g. فولاد."New value: +"Exact Persian trading symbol, e.g. فولاد."
  2. First observedv0.1.0

TDQS

A4.5/5.0
Behavior4/5

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuine behavior beyond that: results are newest-first, dates are Jalali, and an empty list is a signal of a bad symbol rather than a company with no filings. It does not discuss pagination or result size, which is the only remaining gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

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

Two sentences, zero filler: the first defines output and ordering, the second gives the workflow and the failure-mode diagnostic. The most important information (what you get) is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

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 rich annotations and no output schema, the description covers purpose, ordering, calendar convention, prerequisite sequencing, and the empty-result edge case. Nothing an agent needs in order to call it correctly or interpret its result is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the single parameter is fully documented in the schema with an exact Persian-format example (فولاد). The description only reinforces 'one company', adding no format or normalization detail beyond the schema, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource ('List the fiscal year-end dates ... for one company') and adds two distinguishing qualifiers an agent can act on: ordering ('newest first') and calendar ('Jalali'). This is clearly separable from cd_search_letters (which searches statements) and cd_company (which resolves companies).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states an explicit ordering-of-operations rule ('Use it before searching annual statements with cd_search_letters (period_months 12)') and names an alternative tool with the exact parameter that selects it. It also gives a diagnostic for the empty case pointing to cd_company, covering when-not/what-next.

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