BORME API - Spain company registry

Act counts by type, period and province

act_stats

Read-onlyIdempotent

Count BORME acts by act type, period (month, quarter or year) and province: how many companies and entries had mergers, spin-offs, capital increases or any other act type, newest period first.

Use it for trends ("mergers per quarter in Spain since 2020"). To read the acts themselves use search_events.

Returns JSON {grain, count, truncated, rows: [{period, act_type, province, companies, events}], data_through, built_from, built_to, note, plan_window}, plus hidden_by_plan when the plan left buckets out, and not_built (no rows, never zeros) when the range reaches years outside built_from..built_to. period is the bucket's first day by BORME publication date. companies counts distinct companies in that bucket: never add rows up. Province "*" is all of Spain; a community gives one row per province, not a total.

Read-only; one request per call. Needs the pro plan or higher: send your key in the X-API-Key header (https://bormeapi.com/account).

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": "act_stats"
  }
}

Input Schema

Name	Required	Description	Default
`grain`	No	The length of each period, one of "month" (default), "quarter", "year", e.g. "quarter".	month
`limit`	No	Maximum rows, integer 1-5000, e.g. 200 (default 1000); truncated is true when more matched.
`date_to`	No	Optional YYYY-MM-DD, e.g. 2025-12-31; periods starting on or before this day.
`act_types`	No	Optional list of act type enums to count, e.g. ["MERGER_BY_ABSORPTION", "TOTAL_SPIN_OFF"]; omit for every act type. Full list: list_act_types.
`date_from`	No	Optional YYYY-MM-DD, e.g. 2024-01-01; the period holding this day is the first one. Data starts on 2009-01-02.
`provinces`	No	Optional list of BORME province names, accent- and case-insensitive, e.g. ["MADRID", "BARCELONA"]; an autonomous community gives one row per province, e.g. ["Cataluña"]. Omit for the all-provinces rows (province "*").
`by_province`	No	Without provinces: true gives one row per province instead of the all-provinces rows, e.g. true (default false).

Schema Changelog

Changes observed during successful MCP inspections.

AddedNov 4, 2026

TDQS

A4.8/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, non-destructive, closed-world), and the description adds genuinely new behavior: plan-gating that can hide buckets (hidden_by_plan), a no-rows/never-zeros sentinel for out-of-range years, a truncation flag, and a 'built_from..built_to' data window. It also warns that counts are distinct-company counts that must not be summed across rows, which is a real correctness hazard.

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

Conciseness4/5

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

Front-loaded with purpose and then a structured return-shape paragraph; nearly every clause carries distinct information (counting caveat, province semantics, plan gating). It is dense and the middle paragraph runs long, but there is little pure filler.

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?

No output schema exists, so the description must carry return semantics itself, and it enumerates every field family including the conditional ones (hidden_by_plan, not_built, truncated). For a 7-parameter aggregation tool with plan gating and a data window, nothing essential for a correct call is missing.

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 baseline would be 3, but the description adds semantics the schema does not: period is the bucket's first day by BORME publication date, province "*" means all of Spain, and an autonomous community yields one row per province rather than a total. The interaction between provinces and by_province is only partly spelled out in the description text.

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 ('Count BORME acts') plus the three aggregation axes (act type, period, province) and the sort order. It explicitly distinguishes itself from search_events, which returns the acts themselves, so an agent can separate the two without inspecting schemas.

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 a concrete use case ('trends: mergers per quarter in Spain since 2020') and names the alternative to use instead ('To read the acts themselves use search_events'). It also states the access prerequisite (pro plan or higher, X-API-Key header) and a call-cost constraint ('one request per call').

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

All BORME API - Spain company registry tools Inspect

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

Need Help?