Skip to main content
Glama
bormeapi

BORME MCP Server

by bormeapi
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Search registry events

search_events
Read-onlyIdempotent

Search Spanish BORME registry events across many companies by publication date, province, act type, or partial company name to find notices such as insolvencies or incorporations.

Instructions

Search BORME registry events (since 2009) across companies by publication date, province, act type and company name, newest first.

Use it for questions about many companies ("insolvency notices in Valencia in September"). For one known company use company_history; to find a company use search_companies; for one day's totals use daily_digest.

Returns JSON {count, events: [{event_id, date, borme_id, province, company_name, company_slug, acts: [{act_type, act_type_raw, roles, payload}], registral}]}, plus company_name_match, plan_window and hidden_by_plan when they apply. No next page: when count equals limit, narrow the filters.

Read-only; one request per call against your daily quota. Without an API key (X-API-Key header, https://bormeapi.com/account) only the last 7 days are searched (plan_window). An empty page with hidden_by_plan means matches exist outside your plan's window: do not say none exist. A bad date, province or act type is refused with a message naming the fix.

Input Schema

NameRequiredDescriptionDefault
limitNoMaximum events returned, integer 1-200, e.g. 20 (default 50).
date_toNoLatest publication date, inclusive, YYYY-MM-DD, e.g. 2026-09-30. Optional; defaults to the latest day held.
act_typesNoOptional list of act type enums; an event matches if it has any of them, e.g. ["INCORPORATION"] or ["INSOLVENCY_DECLARATION", "INSOLVENCY_STATUS"]. Full list: list_act_types. Barcelona prints some acts as free text under "Otros conceptos": recognised wording gets its own act type (act_type_raw stays "Otros conceptos"; fields.shareholder names a sole shareholder when the text does), and a same-entry revocation and reappointment becomes RE_ELECTIONS. Reprocessed events keep their event_id, but their acts can change.
date_fromNoEarliest publication date, inclusive, YYYY-MM-DD, e.g. 2026-09-01. Optional; data starts on 2009-01-02. Without a key it is moved up to 7 days ago (plan_window says so).
provincesNoOptional list of BORME province names, accent- and case-insensitive, e.g. ["MADRID", "CADIZ", "VIZCAYA"]. An autonomous community stands for all of its provinces, e.g. ["Basque Country"] or ["Cataluña"]. Full list: the resource borme://provinces.
company_name_containsNoOptional part of the company name, case- and accent-insensitive, e.g. "mercadona"; use at least 3 letters or digits for a selective search. % and _ match literally. It filters events; to look a company up by name, call search_companies first.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed6 schema fields changedv2.1.1
    • changedInput schema / properties / act_types / description
      Previous value: -"Act types, e.g. INCORPORATION, APPOINTMENTS, TERMINATIONS, CAPITAL_INCREASE, DISSOLUTION, INSOLVENCY_STATUS (full list: list_act_types)."New value: +"Optional list of act type enums; an event matches if it has any of them, e.g. [\"INCORPORATION\"] or [\"INSOLVENCY_DECLARATION\", \"INSOLVENCY_STATUS\"]. Full list: list_act_types. Barcelona prints some acts as free text under \"Otros conceptos\": recognised wording gets its own act type (act_type_raw stays \"Otros conceptos\"; fields.shareholder names a sole shareholder when the text does), and a same-entry revocation and reappointment becomes RE_ELECTIONS. Reprocessed events keep their event_id, but their acts can change."
    • changedInput schema / properties / company_name_contains / description
      Previous value: -"Part of the company name, at least 3 letters or digits, case-insensitive; % and _ match literally."New value: +"Optional part of the company name, case- and accent-insensitive, e.g. \"mercadona\"; use at least 3 letters or digits for a selective search. % and _ match literally. It filters events; to look a company up by name, call search_companies first."
    • changedInput schema / properties / date_from / description
      Previous value: -"Earliest publication date, YYYY-MM-DD (data starts in 2009)."New value: +"Earliest publication date, inclusive, YYYY-MM-DD, e.g. 2026-09-01. Optional; data starts on 2009-01-02. Without a key it is moved up to 7 days ago (plan_window says so)."
    • changedInput schema / properties / date_to / description
      Previous value: -"Latest publication date, YYYY-MM-DD, inclusive."New value: +"Latest publication date, inclusive, YYYY-MM-DD, e.g. 2026-09-30. Optional; defaults to the latest day held."
    • changedInput schema / properties / limit / description
      Previous value: -"Maximum events returned, 1-200 (default 50)."New value: +"Maximum events returned, integer 1-200, e.g. 20 (default 50)."
    • changedInput schema / properties / provinces / description
      Previous value: -"BORME province names, accent- and case-insensitive, e.g. MADRID, CADIZ, VIZCAYA. An autonomous community stands for all of its provinces, e.g. Basque Country, Cataluña, Andalucía."New value: +"Optional list of BORME province names, accent- and case-insensitive, e.g. [\"MADRID\", \"CADIZ\", \"VIZCAYA\"]. An autonomous community stands for all of its provinces, e.g. [\"Basque Country\"] or [\"Cataluña\"]. Full list: the resource borme://provinces."
  2. Addedv1.1.1
  3. Removedv1.1.0
  4. First observedv0.1.0

TDQS

A4.9/5.0
Behavior5/5

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

Goes well beyond the readOnly/idempotent annotations: discloses one-request-per-call quota consumption, the X-API-Key requirement and its 7-day fallback window, the plan_window and hidden_by_plan fields, the absence of pagination, and that invalid dates/provinces/act types are refused with a corrective message. The warning not to report 'none exist' on a hidden_by_plan empty page is a genuinely important behavioral caveat that no annotation conveys.

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?

Front-loaded with purpose, then routing, then return shape, then operational caveats. Every sentence carries distinct information; the inline return-shape listing is not waste because no output schema exists and it is the only place those fields are documented.

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?

Six optional parameters with 100% schema coverage plus annotations, and the description compensates for the missing output schema by documenting the return envelope and conditional fields. Auth requirements, quota cost, window limits, error behavior and empty-result interpretation are all covered, so an agent has everything needed to call and interpret this tool.

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

Parameters4/5

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

Schema coverage is 100%, so per-parameter meaning is already carried by the schema; the description still adds cross-cutting semantics the schema does not, notably 'newest first' ordering and the no-next-page rule tying `limit` to a narrowing strategy rather than paging. It does not restate per-parameter formats, which is appropriate given the schema's detail.

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 with scope: 'Search BORME registry events (since 2009) across companies by publication date, province, act type and company name, newest first.' It also explicitly distinguishes itself from three siblings by name, so an agent can route correctly 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?

Gives an explicit when-to-use example ('questions about many companies') and then routes the other three cases: one known company -> company_history, find a company -> search_companies, one day's totals -> daily_digest. This is the strongest form of alternative-naming guidance.

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

Deploy Server

Other Tools