Skip to main content
Glama

Esef Search Filings

esef_search_filings
Read-onlyIdempotent

Search the XBRL International filings index (filings.xbrl.org) for published company annual reports. Answers "which European companies have filed an annual report for 2023", "does Nokia have an ESEF filing", "list Finnish filings with validation errors", "Portuguese filings with a period end after 2024-06-30", "Spanish annual reports for 2025". Returns per filing: company name, LEI or national identifier, country, reporting regime, period end, source (xbrl.org, cmvm, cnmv, newsweb or fi) and official publication time where known, XBRL validation error/warning counts, report language, and direct links to the machine-readable xBRL-JSON, the inline-XBRL HTML report and the viewer. Filter by company name (substring), country (ISO-2), regime, exact period end date, calendar year, or a period_end_from/period_end_to date range. Any other argument name is rejected with a user_error rather than silently ignored. 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. Coverage of the current calendar year is sparse, the index lags the filing season; see the response coverage_note. Reports the index-wide match count and echoes back proof that the filters actually applied. Follow up with esef_filing_facts to get the numbers inside a filing.

Example tool call

This call uses example arguments supplied in the tool’s input schema.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "country": "FI",
      "entity_name": "Citycon"
    },
    "name": "esef_search_filings"
  }
}

Input Schema

NameRequiredDescriptionDefault
pageNoPage number for paging through a large match set, starting at 1. Default 1.
sortNoResult ordering: "newest" (most recently added to the index, the default), "oldest", "period_desc" (latest reporting period first), or "period_asc".
yearNoCalendar year of the reporting period end, e.g. 2023. Matches any period ending in that year.
limitNoFilings to return, 1-100. Default 20.
regimeNoReporting regime: "ESEF" for the European Single Electronic Format annual financial report, or "UAIFRS" for Ukrainian IFRS filings. Omit to search both.
countryNoISO-2 country of the filing jurisdiction: AT, BE, CY, CZ, DK, ES, FI, FR, GB, GR, IS, IT, LT, MT, NL, NO, PL, PT, RO, SE (ESEF) or UA (UAIFRS). LU, SI, EE, IE and BG are also accepted, these five are looked up live (see the coverage note above) and pinning `country` to one of them is required to trigger that lookup; GR is always live-augmented in addition to the index.
period_endNoExact reporting period end date, ISO format, e.g. "2023-12-31". Takes precedence over `year` and over `period_end_from`/`period_end_to`.
entity_nameNoCompany name or fragment, case-insensitive substring match against the filer name (e.g. "Nokia", "Citycon", "Vodafone", "Siemens").
with_errorsNoSet true to return only filings that failed XBRL validation (error_count greater than zero).
period_end_toNoOnly filings whose reporting period end is on or before this ISO date, e.g. "2024-12-31". Combine with `period_end_from` for a range; either bound may be used alone. Ignored if `period_end` (exact) is also set; takes precedence over `year`.
period_end_fromNoOnly filings whose reporting period end is on or after this ISO date, e.g. "2024-01-01". Combine with `period_end_to` for a range; either bound may be used alone. Ignored if `period_end` (exact) is also set; takes precedence over `year`.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / country / description
      Previous value: -"ISO-2 country of the filing jurisdiction: AT, BE, CY, CZ, DK, ES, FI, FR, GB, GR, IS, IT, LT, MT, NL, NO, PL, PT, RO, SE (ESEF) or UA (UAIFRS). LU, SI, EE, IE and BG are also accepted — these five are looked up live (see the coverage note above) and pinning `country` to one of them is required to trigger that lookup; GR is always live-augmented in addition to the index."New value: +"ISO-2 country of the filing jurisdiction: AT, BE, CY, CZ, DK, ES, FI, FR, GB, GR, IS, IT, LT, MT, NL, NO, PL, PT, RO, SE (ESEF) or UA (UAIFRS). LU, SI, EE, IE and BG are also accepted, these five are looked up live (see the coverage note above) and pinning `country` to one of them is required to trigger that lookup; GR is always live-augmented in addition to the index."
  2. Changed2 schema fields changed
    • changedInput schema / examples
      Previous value: -[
      -  {
      -    "country": "FI",
      -    "entity_name": "Citycon"
      -  },
      -  {
      -    "country": "GB",
      -    "limit": 10,
      -    "sort": "period_desc",
      -    "year": 2024
      -  },
      -  {
      -    "limit": 5,
      -    "regime": "UAIFRS",
      -    "year": 2021
      -  },
      -  {
      -    "country": "PT",
      -    "limit": 50,
      -    "year": 2025
      -  }
      -]New value: +[
      +  {
      +    "country": "FI",
      +    "entity_name": "Citycon"
      +  },
      +  {
      +    "country": "LU",
      +    "entity_name": "ArcelorMittal"
      +  },
      +  {
      +    "country": "EE",
      +    "entity_name": "Tallink"
      +  },
      +  {
      +    "country": "GB",
      +    "limit": 10,
      +    "sort": "period_desc",
      +    "year": 2024
      +  },
      +  {
      +    "limit": 5,
      +    "regime": "UAIFRS",
      +    "year": 2021
      +  },
      +  {
      +    "country": "PT",
      +    "limit": 50,
      +    "year": 2025
      +  },
      +  {
      +    "country": "IE",
      +    "entity_name": "Ryanair"
      +  },
      +  {
      +    "country": "GR",
      +    "entity_name": "Jumbo"
      +  },
      +  {
      +    "country": "BG",
      +    "entity_name": "Vipom"
      +  }
      +]
    • changedInput schema / properties / country / description
      Previous value: -"ISO-2 country of the filing jurisdiction: AT, BE, CY, CZ, DK, ES, FI, FR, GB, GR, IS, IT, LT, NL, NO, PL, PT, RO, SE (ESEF) or UA (UAIFRS)."New value: +"ISO-2 country of the filing jurisdiction: AT, BE, CY, CZ, DK, ES, FI, FR, GB, GR, IS, IT, LT, MT, NL, NO, PL, PT, RO, SE (ESEF) or UA (UAIFRS). LU, SI, EE, IE and BG are also accepted — these five are looked up live (see the coverage note above) and pinning `country` to one of them is required to trigger that lookup; GR is always live-augmented in addition to the index."
  3. Changed4 schema fields changed
    • changedInput schema / examples
      Previous value: -[
      -  {
      -    "country": "FI",
      -    "entity_name": "Citycon"
      -  },
      -  {
      -    "country": "GB",
      -    "limit": 10,
      -    "sort": "period_desc",
      -    "year": 2024
      -  },
      -  {
      -    "limit": 5,
      -    "regime": "UAIFRS",
      -    "year": 2021
      -  }
      -]New value: +[
      +  {
      +    "country": "FI",
      +    "entity_name": "Citycon"
      +  },
      +  {
      +    "country": "GB",
      +    "limit": 10,
      +    "sort": "period_desc",
      +    "year": 2024
      +  },
      +  {
      +    "limit": 5,
      +    "regime": "UAIFRS",
      +    "year": 2021
      +  },
      +  {
      +    "country": "PT",
      +    "limit": 50,
      +    "year": 2025
      +  }
      +]
    • changedInput schema / properties / period_end / description
      Previous value: -"Exact reporting period end date, ISO format, e.g. \"2023-12-31\". Takes precedence over `year`."New value: +"Exact reporting period end date, ISO format, e.g. \"2023-12-31\". Takes precedence over `year` and over `period_end_from`/`period_end_to`."
    • addedInput schema / properties / period_end_from
      Added value: +{
      +  "description": "Only filings whose reporting period end is on or after this ISO date, e.g. \"2024-01-01\". Combine with `period_end_to` for a range; either bound may be used alone. Ignored if `period_end` (exact) is also set; takes precedence over `year`.",
      +  "type": "string"
      +}
    • addedInput schema / properties / period_end_to
      Added value: +{
      +  "description": "Only filings whose reporting period end is on or before this ISO date, e.g. \"2024-12-31\". Combine with `period_end_from` for a range; either bound may be used alone. Ignored if `period_end` (exact) is also set; takes precedence over `year`.",
      +  "type": "string"
      +}
  4. First observed

TDQS

A4/5.0
Behavior5/5

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

Annotations already declare read-only, open-world, idempotent, non-destructive behavior, but the description adds substantial context: index coverage counts, source-specific lag, live-lookup rules for LU/SI/EE/GR/IE/BG, missing `period_end` for IE, inferred GR `period_end`, and user_error on unknown arguments. This is rich behavioral disclosure beyond structured fields.

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?

After a strong opening, the description becomes a very long country-by-country OAM enumeration with repeated "only source for FY2024/FY2025" phrasing and internal-sounding language such as "Bruce-authorized live lookups." It is informative but poorly structured and much longer than needed.

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 an 11-parameter tool with no output schema and complex source-specific behavior, the description covers return fields, coverage caveats, live-lookup limitations, and missing/inferred data thoroughly. An agent has enough information to call it correctly, even if the presentation is bloated.

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%, and the input schema already documents country codes, precedence rules, sorting, paging, and substring matching. The description restates the filter meanings and the live-lookup `country` requirement but adds little semantic detail beyond what the schema already says.

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

Purpose4/5

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

States a specific verb ("Search") and resource ("XBRL International filings index (filings.xbrl.org)") and adds example questions that clarify scope. It routes follow-up work to esef_filing_facts but never mentions esef_entity_filings, the closest sibling, so sibling differentiation is incomplete.

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?

Gives clear usage conditions: filter options, the need to pin `country` for live-lookup jurisdictions, and the esef_filing_facts follow-up. It does not say when to choose this tool over esef_entity_filings or when not to use it, so alternatives and exclusions are only partially covered.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.