Skip to main content
Glama

Esef Filings

by io.github.pipeworx-io
OverviewDiscussionsAdmin

Esef Filing Facts

esef_filing_facts
Read-onlyIdempotent

Read the actual IFRS financial facts out of one published annual report — revenue, profit or loss, total assets, equity, operating cash flow, earnings per share and every other tagged figure, with the currency, the exact reporting period and the XBRL concept name. This is the numbers hop: esef_search_filings and esef_entity_filings prove a filing exists, this one opens its machine-readable xBRL-JSON report and returns what the company reported. 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. Identify the filing by fxo_id from a search result (a Portuguese CMVM filing looks like "cmvm-1355933", a Spanish CNMV filing "cnmv-20912", a Norwegian NewsWeb filing "newsweb-668785-321602", a Swedish FI filing "fi-61807", a Belgian STORI filing "fsma-5c08f790-404c-4121-bd0b-0cf3350455da", a Maltese MSE filing "mse-BOV_20251231_CON_AFR_529900RWC8ZYB066JF16_20260326114707204", a Croatian SRPI filing "hanfa-1214588", a Hungarian MNB filing "mnb-909016", a Lithuanian oam.lt filing "oamlt-468051-338788", a Romanian ASF filing "asf-SNP-20260319180945", a Cypriot CSE filing "cse-222818-223858", a Latvian CSRI filing "csri-24777-1"), or just by company name or LEI plus an optional year and the latest matching report is used (the national copy for Portuguese, Spanish, Norwegian, Swedish, Belgian, Maltese, Croatian, Hungarian, Lithuanian, Romanian, Cypriot and Latvian issuers, otherwise the English-language edition). A live-lookup id from esef_search_filings/esef_entity_filings for Luxembourg, Slovenia, Estonia, Greece, Ireland or Bulgaria (fxo_id starting "luxoam-", "seonet-", "fi_ee-", "athex-", "oamie-" or "beis-") has no xBRL-JSON to read — this tool declines and points at that filing's package_url/source_url instead. Pass concept to pull one line item (case-insensitive substring of the IFRS concept, e.g. "Revenue", "ProfitLoss", "Assets", "Equity", "CashFlows"); omit it for a headline projection of the main statement figures. Facts repeated across statements are collapsed, consolidated totals are separated from segment and equity-component breakdowns, and the full concept inventory of the report is returned so a follow-up query can target any line item.

Input Schema

NameRequiredDescriptionDefault
yearNoCalendar year of the reporting period end, e.g. 2023. Used with `entity`. Omit for the most recent filed period.
limitNoFacts to return, 1-500. Default 60.
entityNoCompany name, LEI, or national registration number, used when no fxo_id is available. Combine with `year` to choose a financial year; the latest English-language edition is preferred.
fxo_idNoFiling identifier from esef_search_filings or esef_entity_filings, e.g. "549300P8N0P6KDGTJ206-2022-12-31-ESEF-FI-0", "cmvm-1355933" for a Portuguese filing read from CMVM, "cnmv-20912" for a Spanish filing read from CNMV, "newsweb-668785-321602" for a Norwegian filing read from Oslo Børs NewsWeb, "fi-61807" for a Swedish filing read from Finansinspektionen, "fsma-5c08f790-404c-4121-bd0b-0cf3350455da" for a Belgian filing read from FSMA STORI, "mse-BOV_20251231_CON_AFR_529900RWC8ZYB066JF16_20260326114707204" for a Maltese filing read from the Malta Stock Exchange OAM, "hanfa-1214588" for a Croatian filing read from HANFA SRPI, "mnb-909016" for a Hungarian filing read from the MNB, "oamlt-468051-338788" for a Lithuanian filing read from oam.lt, "asf-SNP-20260319180945" for a Romanian filing read from the ASF OAM, "cse-222818-223858" for a Cypriot filing read from the Cyprus Stock Exchange OAM, or "csri-24777-1" for a Latvian filing read from CSRI. Most precise way to name a filing.
conceptNoCase-insensitive substring of the IFRS concept name to return, e.g. "Revenue", "ProfitLoss", "Assets", "Equity", "CashFlowsFromUsedInOperatingActivities", "EarningsPerShare". Omit for the headline projection.
include_dimensionedNoSet true to also return facts broken down by an XBRL axis — per segment, per equity component, per class of asset. Default false, which returns consolidated group totals only.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / fxo_id / description
      Previous value: -"Filing identifier from esef_search_filings or esef_entity_filings, e.g. \"549300P8N0P6KDGTJ206-2022-12-31-ESEF-FI-0\", \"cmvm-1355933\" for a Portuguese filing read from CMVM, \"cnmv-20912\" for a Spanish filing read from CNMV, \"newsweb-668785-321602\" for a Norwegian filing read from Oslo Børs NewsWeb, \"fi-61807\" for a Swedish filing read from Finansinspektionen, or \"fsma-5c08f790-404c-4121-bd0b-0cf3350455da\" for a Belgian filing read from FSMA STORI. Most precise way to name a filing."New value: +"Filing identifier from esef_search_filings or esef_entity_filings, e.g. \"549300P8N0P6KDGTJ206-2022-12-31-ESEF-FI-0\", \"cmvm-1355933\" for a Portuguese filing read from CMVM, \"cnmv-20912\" for a Spanish filing read from CNMV, \"newsweb-668785-321602\" for a Norwegian filing read from Oslo Børs NewsWeb, \"fi-61807\" for a Swedish filing read from Finansinspektionen, \"fsma-5c08f790-404c-4121-bd0b-0cf3350455da\" for a Belgian filing read from FSMA STORI, \"mse-BOV_20251231_CON_AFR_529900RWC8ZYB066JF16_20260326114707204\" for a Maltese filing read from the Malta Stock Exchange OAM, \"hanfa-1214588\" for a Croatian filing read from HANFA SRPI, \"mnb-909016\" for a Hungarian filing read from the MNB, \"oamlt-468051-338788\" for a Lithuanian filing read from oam.lt, \"asf-SNP-20260319180945\" for a Romanian filing read from the ASF OAM, \"cse-222818-223858\" for a Cypriot filing read from the Cyprus Stock Exchange OAM, or \"csri-24777-1\" for a Latvian filing read from CSRI. Most precise way to name a filing."
  2. Changed2 schema fields changed
    • changedInput schema / examples
      Previous value: -[
-  {
-    "entity": "Citycon",
-    "year": 2022
-  },
-  {
-    "concept": "ProfitLoss",
-    "fxo_id": "549300P8N0P6KDGTJ206-2022-12-31-ESEF-FI-0"
-  },
-  {
-    "concept": "Assets",
-    "entity": "Vodafone",
-    "limit": 10
-  }
-]New value: +[
+  {
+    "entity": "Citycon",
+    "year": 2022
+  },
+  {
+    "concept": "ProfitLoss",
+    "fxo_id": "549300P8N0P6KDGTJ206-2022-12-31-ESEF-FI-0"
+  },
+  {
+    "concept": "Assets",
+    "entity": "Vodafone",
+    "limit": 10
+  },
+  {
+    "concept": "Revenue",
+    "entity": "Jeronimo Martins",
+    "limit": 5,
+    "year": 2025
+  },
+  {
+    "concept": "ProfitLoss",
+    "fxo_id": "cmvm-1355933",
+    "limit": 5
+  }
+]
    • changedInput schema / properties / fxo_id / description
      Previous value: -"Filing identifier from esef_search_filings or esef_entity_filings, e.g. \"549300P8N0P6KDGTJ206-2022-12-31-ESEF-FI-0\". Most precise way to name a filing."New value: +"Filing identifier from esef_search_filings or esef_entity_filings, e.g. \"549300P8N0P6KDGTJ206-2022-12-31-ESEF-FI-0\", \"cmvm-1355933\" for a Portuguese filing read from CMVM, \"cnmv-20912\" for a Spanish filing read from CNMV, \"newsweb-668785-321602\" for a Norwegian filing read from Oslo Børs NewsWeb, \"fi-61807\" for a Swedish filing read from Finansinspektionen, or \"fsma-5c08f790-404c-4121-bd0b-0cf3350455da\" for a Belgian filing read from FSMA STORI. Most precise way to name a filing."
  3. First observed

TDQS

A4.1/5.0
Behavior4/5

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

Annotations already declare readOnly/idempotent/destructive=false/openWorld, so safety is covered; the description goes further by disclosing that repeated facts are collapsed, consolidated totals are separated from segment breakdowns, the full concept inventory is returned, live-lookup filings are never mirrored, and GR period_end is inferred and flagged. Much of the remainder is coverage/bookkeeping rather than tool behavior, which keeps it from a full 5.

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?

The core value is front-loaded in the first two sentences, but the body becomes a sprawling multi-hundred-word run-on enumerating each country's OAM and repeatedly restating 'the only source for X FY2025 reports'. The essential calling guidance is buried under coverage trivia that does not earn its place in a tool description.

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?

There is no output schema, yet the description explains what comes back (currency, reporting period, XBRL concept, headline projection, concept inventory) and handles the complex multi-regime edge cases (id formats per source, inferred period_end, live-lookup refusals). It is complete enough to call correctly, apart from the phantom country/regime parameters.

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%, so the six real parameters (year, limit, entity, fxo_id, concept, include_dimensioned) are already documented and 3 is the baseline. The description adds little beyond the schema for these, and problematically it repeatedly instructs the caller to pass `country` or `regime`, which do not exist as schema properties — guidance an agent cannot act on.

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 opening sentence names a specific verb and resource (read IFRS financial facts from one annual report) and enumerates concrete outputs (revenue, profit, assets, equity, cash flow, EPS, XBRL concept). It then explicitly differentiates itself from siblings: esef_search_filings/esef_entity_filings prove a filing exists, while this one opens the xBRL-JSON report and returns what the company reported. An agent can distinguish purpose without opening any schema.

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 routes the agent explicitly: identify a filing by fxo_id from a search result, or by company name/LEI plus optional year, and it names the cases where the tool declines (live-lookup ids for LU/SI/EE/GR/IE/BG) with the fallback (package_url/source_url). It also tells the caller to pass country for pinned-country lookups and to use concept for a single line item vs a headline projection.

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