Skip to main content
Glama
codal-mcp

codal-mcp

by sepehr071

Search Codal disclosures

cd_search_letters
Read-onlyIdempotent

Search Codal disclosure letters from Iranian listed companies by symbol, title, date, category, or tracing number, returning newest results first with pagination.

Instructions

Search codal.ir disclosures (letters) of Iranian listed companies, newest first, 20 per page.

No filters lists the newest letters of all companies. total = matches, pages = page count. Pass a letter's tracing_no to cd_letter to read it. No results: check the symbol with cd_company or widen filters.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "cd_search_letters"
  }
}

Input Schema

NameRequiredDescriptionDefault
pageNoResult page (20 letters).
titleNoPersian words in the letter title, e.g. افزایش سرمایه.
symbolNoExact Persian trading symbol, e.g. فولاد (find with cd_company).
to_dateNoSent on/before this Jalali date.
categoryNoLetter group: 1 financial statements, dividend schedules; 2 material info, clarifications; 3 monthly activity, portfolios; 4 articles, prospectuses; 5 board, audit committee; 6 shareholder meetings; 7 capital increase; 8 exchange notices; 9 SEO notices; 10 other; 11 debt securities.
from_dateNoSent on/after this Jalali date, e.g. 1405/07/01.
tracing_noNoTracing number (شماره پیگیری) of one letter.
letter_typeNoLetter type id from cd_letter_types, e.g. 6 financial statements, 58 monthly activity, 20 AGM decisions, 30 dividend schedule.
period_monthsNoReport period in months: 12 annual, 6 half-year, 3 quarterly, 1 monthly.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed9 schema fields changedv0.2.0
    • changedInput schema / properties / category / description
      Previous value: -"Letter group: 1 financial statements, board reports and dividend schedules; 2 material information, clarifications and EPS forecasts; 3 monthly activity and portfolio reports; 4 articles of association and prospectuses; 5 board and audit committee; 6 shareholder meetings (invitations, decisions); 7 capital increase; 8 exchange notices; 9 SEO (regulator) notices; 10 other; 11 debt securities."New value: +"Letter group: 1 financial statements, dividend schedules; 2 material info, clarifications; 3 monthly activity, portfolios; 4 articles, prospectuses; 5 board, audit committee; 6 shareholder meetings; 7 capital increase; 8 exchange notices; 9 SEO notices; 10 other; 11 debt securities."
    • changedInput schema / properties / from_date / description
      Previous value: -"Sent on or after this Jalali date, YYYY/MM/DD, e.g. 1405/07/01."New value: +"Sent on/after this Jalali date, e.g. 1405/07/01."
    • changedInput schema / properties / letter_type / description
      Previous value: -"One letter type id from cd_letter_types, e.g. 6 interim/annual financial statements, 58 monthly activity report, 20 annual general meeting decisions, 11 material information, 30 dividend payment schedule."New value: +"Letter type id from cd_letter_types, e.g. 6 financial statements, 58 monthly activity, 20 AGM decisions, 30 dividend schedule."
    • changedInput schema / properties / page / description
      Previous value: -"Result page, 20 letters each, newest first."New value: +"Result page (20 letters)."
    • changedInput schema / properties / period_months / description
      Previous value: -"Only reports covering this many months, e.g. 12 annual, 6 half-year, 3 quarterly, 1 monthly."New value: +"Report period in months: 12 annual, 6 half-year, 3 quarterly, 1 monthly."
    • changedInput schema / properties / symbol / description
      Previous value: -"Exact trading symbol in Persian, e.g. فولاد or خودرو. Use cd_company to find it."New value: +"Exact Persian trading symbol, e.g. فولاد (find with cd_company)."
    • changedInput schema / properties / title / description
      Previous value: -"Words that must appear in the letter title, in Persian, e.g. سود or افزایش سرمایه."New value: +"Persian words in the letter title, e.g. افزایش سرمایه."
    • changedInput schema / properties / to_date / description
      Previous value: -"Sent on or before this Jalali date, YYYY/MM/DD."New value: +"Sent on/before this Jalali date."
    • changedInput schema / properties / tracing_no / description
      Previous value: -"Codal tracing number (شماره پیگیری) of one letter, e.g. 1612323."New value: +"Tracing number (شماره پیگیری) of one letter."
  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, non-destructive, and open-world, so the safety profile is covered. The description adds useful behavior beyond them: fixed page size, newest-first ordering, and the meaning of the `total` and `pages` response fields. It stops short of noting any rate limits or upstream availability caveats, so it is strong but not exhaustive.

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?

Three short sentences with no filler: scope and paging are front-loaded, then the empty-state behavior. Every clause carries operational information.

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 nine-parameter, zero-required search tool with no output schema, the description supplies paging size, ordering, and the two return-value fields an agent needs to paginate, plus routing to the follow-up and diagnostic tools. Nothing essential to a correct call 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 description coverage is 100%, including detailed category and letter_type enumerations and Jalali date examples, so the schema already does the heavy lifting. The description adds only the tracing_no-to-cd_letter linkage and the total/pages semantics, which is the expected baseline when parameters are fully documented downstream.

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?

States a specific verb and resource ("Search codal.ir disclosures (letters) of Iranian listed companies") plus result ordering (newest first) and page size (20 per page). It also distinguishes itself from siblings by naming cd_letter for reading a single letter and cd_company for symbol lookup.

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?

Explicitly covers the no-filter case ("No filters lists the newest letters of all companies"), the follow-up path (pass tracing_no to cd_letter), and the empty-result recovery path (verify symbol with cd_company or widen filters). An agent knows both when to call this and what to do next.

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