Skip to main content
Glama

Esef Filings

by io.github.pipeworx-io
OverviewDiscussionsAdmin

Esef Entity Filings

esef_entity_filings
Read-onlyIdempotent

List every annual report one company has published to the XBRL International filings index, resolving a company name, LEI, or national registration number to the filer. Answers "what years has Citycon filed?" or "give me Nokia's latest annual report". Returns the resolved company (name, identifier, and how the match was made) plus each filing with period end, country, regime, validation error/warning counts and links to the xBRL-JSON, HTML report and viewer. Covers 25,640 filings in two regimes: ESEF (~16,000 annual financial reports from 19 European countries — AT BE CY CZ DK ES FI FR GB GR IS IT LT NL NO PL PT RO SE) and UAIFRS (~9,600 Ukrainian IFRS filings, country UA). Pass country or regime to pin the scope you mean. Portuguese (PT), Spanish (ES) and Norwegian (NO) ESEF reports are also read directly from where each country publishes them — CMVM for Portugal, CNMV for Spain, Oslo Børs NewsWeb for Norway — so PT, ES and NO coverage follows official publication (typically within a day) rather than the index's months-long lag; each row names its source and those rows carry the official published_at. Swedish (SE) reports are likewise read from Finansinspektionen (FI), the Swedish OAM, which is the only source for Swedish FY2025 reports, Belgian (BE) reports from the FSMA's STORI database, the Belgian OAM, Maltese (MT) reports from the Malta Stock Exchange OAM, the only source for Maltese FY2025 reports, Croatian (HR) reports from HANFA's SRPI, the Croatian OAM and the only source for Croatian FY2025 reports, Hungarian (HU) reports from the MNB's Közzétételek site, the Hungarian OAM and the only source for Hungarian FY2025 reports, Lithuanian (LT) reports from oam.lt, the Lithuanian OAM run by Nasdaq Vilnius, as well as the index, Romanian (RO) reports from the ASF OAM, the only source for Romanian FY2025 reports, Cypriot (CY) reports from the Cyprus Stock Exchange public OAM, the only source for Cypriot FY2025 reports, and Latvian (LV) reports from CSRI, the Latvian OAM, the only source for Latvian FY2024 and FY2025 reports. Luxembourgish (LU), Slovenian (SI) and Estonian (EE) reports are also answered directly from the LuxSE OAM, SEOnet or the Estonian FSA's OAM for each request, because these three OAMs' terms require the operator's consent for commercial reuse of their documents beyond ordinary access; a lookup made once on a caller's behalf is not that. Greek (GR) and Irish (IE) reports are likewise answered directly from Euronext Athens and the Euronext Dublin OAM for each request — these two sites' terms forbid bots and automated access outright rather than just reuse, so these are Bruce-authorized live lookups rather than a re-derivation of the usual reasoning, kept live and never mirrored for the same reason. Bulgarian (BG) reports are answered directly from BEIS, a Bulgarian disclosure agent whose terms ask only for attribution (unlike Bulgaria's other disclosure agents, which this pack does not call) and covers only the roughly three issuers that use it. None of GR/IE/BG carry machine-readable facts (esef_filing_facts declines a live-lookup id and points at its package_url/source_url); SI is limited to the ~20 most recent Slovenian annual-report announcements; IE rows carry no period_end (Irish fiscal year ends vary by issuer); GR's period_end is inferred from the filing's reporting year, not stated exactly, and flagged period_end_inferred. All six (LU, SI, EE, GR, IE, BG) are pinned-country lookups only — pass country explicitly. The same annual report is frequently indexed once per language edition (a Finnish and an English row for one financial year), so results are also grouped into distinct reports with the English edition preferred, and both a filing count and a distinct-report count are returned.

Input Schema

NameRequiredDescriptionDefault
limitNoFilings to return, 1-100. Default 50.
entityYesCompany name ("Citycon", "Nokia"), 20-character LEI ("549300P8N0P6KDGTJ206"), or national registration number for Ukrainian filers ("32033791"). Names are matched case-insensitively as a substring; the response says exactly which filer was chosen.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / examples
      Previous value: -[
-  {
-    "entity": "Nokia"
-  },
-  {
-    "entity": "549300P8N0P6KDGTJ206"
-  },
-  {
-    "entity": "259400A8SZP10GB5IB19"
-  }
-]New value: +[
+  {
+    "entity": "Nokia"
+  },
+  {
+    "entity": "Krka"
+  },
+  {
+    "entity": "549300P8N0P6KDGTJ206"
+  },
+  {
+    "entity": "259400A8SZP10GB5IB19"
+  },
+  {
+    "entity": "Ryanair"
+  },
+  {
+    "entity": "Vipom"
+  }
+]
  2. Changed1 schema field changed
    • changedInput schema / examples
      Previous value: -[
-  {
-    "entity": "Nokia"
-  },
-  {
-    "entity": "549300P8N0P6KDGTJ206"
-  }
-]New value: +[
+  {
+    "entity": "Nokia"
+  },
+  {
+    "entity": "549300P8N0P6KDGTJ206"
+  },
+  {
+    "entity": "259400A8SZP10GB5IB19"
+  }
+]
  3. First observed

TDQS

A4.1/5.0
Behavior5/5

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld, non-destructive), and the description adds substantial context beyond them: per-country source provenance and freshness, the omission of `period_end` for IE, the `period_end_inferred` flag for GR, the ~20-row limit for SI, the language-edition duplication and English-preferred grouping, plus legal/terms restrictions governing live lookups. This is unusually rich disclosure for a read tool.

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

Conciseness2/5

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

Purpose and examples are correctly front-loaded, but the body is a 400+ word wall of prose whose long passages on OAM terms, consent and bot policies do not help an agent decide or invoke. The single unbroken paragraph buries the operationally relevant constraints (inferred periods, missing period_end, grouped counts) inside tangential legal detail.

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

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the return-shape burden well: it enumerates the resolved company fields, per-filing period end, country, regime, validation counts and artifact links, plus filing vs distinct-report counts. It falls short of 5 only because the country/regime instructions reference parameters the schema does not declare, leaving a real ambiguity unresolved.

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%, so baseline is 3, and the description does add meaning for `entity` (LEI format, national registration numbers, case-insensitive substring matching) and reinforces resolution behavior. The offsetting flaw is that it repeatedly instructs callers to 'pass `country` or `regime`', but neither parameter exists in the input schema — guidance that points at non-existent parameters dilutes the value it adds.

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 first sentence states a specific verb and resource: 'List every annual report one company has published to the XBRL International filings index', and adds that it resolves a name, LEI or registration number to the filer. It gives concrete example questions ('what years has Citycon filed?') and names the sibling tools' domain (esef_filing_facts) explicitly, so an agent can distinguish it without opening schemas.

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

Usage Guidelines4/5

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

It gives clear usage conditions, including 'Pass `country` or `regime` to pin the scope you mean' and 'All six (LU, SI, EE, GR, IE, BG) are pinned-country lookups only — pass `country` explicitly'. However, it never names or contrasts the sibling tools (esef_search_filings, esef_filing_facts) as alternatives, so routing between ESEF tools remains inferential.

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

All Esef Filings toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources