Skip to main content
Glama
Sign In

PeppolStatus

by com.peppolstatus
OverviewDiscussionsAdmin

get_participants_mix

Read-only

Get a filtered participant breakdown

The participant set broken down by country, entity type, NACE Rev. 2.1 division, size class, region and serving Access Point, over a FILTERED slice — so a breakdown stays true while the list is cut down. The filters are the same names and shapes as GET /v1/participants.

TWO SOURCES, one shape, named by source. A request that narrows on NOTHING is answered from the hourly rollup (source: "rollup", with refreshed_at) — the whole-network breakdown, no scan. A request that narrows is computed live (source: "slice").

BOUNDED BY DESIGN. A live slice is computed only while it is narrow (under an internal cap of 10,000 participants). A slice wider than the cap, or a request carrying a filter this endpoint cannot express (doctype, transport_profile, q, host, sub_provider), answers degraded: true with every mix null — never a wrong number and never an error. Callers fall back to the whole-network breakdown on GET /v1/stats/participants.

Counts are sparse the same way the rollup facets are: company enrichment covers a handful of registers, so every mix except country_mix sums BELOW participant_count and the un-enriched remainder is derived from the total rather than served as a bucket. ap_mix names the busiest Access Point Seats and folds the rest into one __other__ bucket.

Input Schema

NameRequiredDescriptionDefault
apNoComma-array of serving Access Point SeatIDs (`PBE000123,PNO000456`).
smpNoComma-array of current SMP hostnames (`smp1.example,smp2.example`).
sizeNoComma-array of company size band codes, as stored (`12,21`): the INSEE trancheEffectifs codes for FR (`NN` = unknown), and for NO the same code set plus `1-4`.
regionNoComma-array of company seat region codes (`BE-BRU,BE-VLG`).
schemeNoComma-array of Peppol identifier schemes.
sectorNoComma-array of 2-digit NACE Rev. 2.1 divisions (`47,62`).
countryNoComma-array of ISO-3166-1 alpha-2 country codes. Matched on the participant's card country, falling back to the country its ICD prefix implies — the same rule `country_mix` buckets on.
not_smpNoComma-array of SMP hostnames to EXCLUDE. Rows with no value are KEPT — excluding a value never drops the un-enriched remainder. Combines with its include twin: `?region=NO-03&not_region=NO-32` applies both.
not_sizeNoComma-array of company size band codes (as stored: `21,NN`; FR and NO only) to EXCLUDE. Rows with no value are KEPT — excluding a value never drops the un-enriched remainder. Combines with its include twin: `?region=NO-03&not_region=NO-32` applies both.
postcodeNoComma-array of company seat postcodes.
not_regionNoComma-array of company seat region codes (`NO-32,BE-BRU`) to EXCLUDE. Rows with no value are KEPT — excluding a value never drops the un-enriched remainder. Combines with its include twin: `?region=NO-03&not_region=NO-32` applies both.
not_sectorNoComma-array of 2-digit NACE Rev. 2.1 divisions (`47,62`) to EXCLUDE. Rows with no value are KEPT — excluding a value never drops the un-enriched remainder. Combines with its include twin: `?region=NO-03&not_region=NO-32` applies both.
provenanceNoComma-array of provenance values.
registeredNoFilter by current SML registration state.
vat_liableNoFilter by company VAT-liable / mandate-scope flag.
entity_typeNoComma-array of company legal-form families (`company`,`natural_person`,`association`,`public`), from the company-register enrichment denormalized onto the participant.
not_countryNoComma-array of country codes (`NO,SE`) to EXCLUDE. Rows with no value are KEPT — excluding a value never drops the un-enriched remainder. Combines with its include twin: `?region=NO-03&not_region=NO-32` applies both.
not_entity_typeNoComma-array of company legal-form families (`company`,`natural_person`,`association`,`public`) to EXCLUDE. Rows with no value are KEPT — excluding a value never drops the un-enriched remainder. Combines with its include twin: `?region=NO-03&not_region=NO-32` applies both.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • changedInput schema / properties / not_size / description
      Previous value: -"Comma-array of company size classes (as stored; SIRENE only) to EXCLUDE. Rows with no value are KEPT — excluding a value never drops the un-enriched remainder. Combines with its include twin: `?region=NO-03&not_region=NO-32` applies both."New value: +"Comma-array of company size band codes (as stored: `21,NN`; FR and NO only) to EXCLUDE. Rows with no value are KEPT — excluding a value never drops the un-enriched remainder. Combines with its include twin: `?region=NO-03&not_region=NO-32` applies both."
    • changedInput schema / properties / size / description
      Previous value: -"Comma-array of company size classes (as stored; SIRENE only)."New value: +"Comma-array of company size band codes, as stored (`12,21`): the INSEE trancheEffectifs codes for FR (`NN` = unknown), and for NO the same code set plus `1-4`."
  2. Changed2 schema fields changed
    • changedInput schema / properties / not_sector / description
      Previous value: -"Comma-array of 2-digit NACE divisions (`47,62`) to EXCLUDE. Rows with no value are KEPT — excluding a value never drops the un-enriched remainder. Combines with its include twin: `?region=NO-03&not_region=NO-32` applies both."New value: +"Comma-array of 2-digit NACE Rev. 2.1 divisions (`47,62`) to EXCLUDE. Rows with no value are KEPT — excluding a value never drops the un-enriched remainder. Combines with its include twin: `?region=NO-03&not_region=NO-32` applies both."
    • changedInput schema / properties / sector / description
      Previous value: -"Comma-array of 2-digit NACE divisions (`47,62`)."New value: +"Comma-array of 2-digit NACE Rev. 2.1 divisions (`47,62`)."
  3. Added

TDQS

A4.6/5.0
Behavior5/5

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

Annotations only supply readOnlyHint, and the description carries the rest: the source selection logic, the 10,000-participant internal cap, the `degraded: true` all-null response for unsupported filters (doctype, transport_profile, q, host, sub_provider), sparse-enrichment behavior, and the `__other__` folding in `ap_mix`. This is exactly the beyond-annotation context the bar asks for.

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-loads the purpose in the first line and organizes the rest under short bolded headers (TWO SOURCES, BOUNDED BY DESIGN), so structure is strong. It is dense and longer than strictly necessary, with some repetition of the un-enriched remainder point, which keeps it from a 5.

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 describe returns, and it does: it names `source`, `refreshed_at`, `degraded`, `participant_count`, the per-dimension mix names, null behavior, and the `__other__` bucket. For an 18-parameter, 0-required tool this is a complete operational picture.

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 the baseline is 3, but the description adds real meaning: it confirms the filters share names/shapes with `GET /v1/participants`, and enumerates the filters this endpoint cannot express, which the schema does not say. The un-enriched-remainder note also clarifies how include/exclude params behave on missing values.

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+resource ('Get a filtered participant breakdown') and enumerates the dimensions (country, entity type, NACE division, size class, region, Access Point). It also positions itself against related endpoints by naming `GET /v1/stats/participants` as the fallback for whole-network breakdowns, so an agent can distinguish it from sibling stats tools.

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?

Explains the two operating regimes clearly: a request narrowing on nothing is served from the hourly rollup, a narrowing request is computed live, and callers should fall back to `GET /v1/stats/participants` when degraded. It also notes the filters mirror `GET /v1/participants`. It lacks an explicit 'use this instead of X when Y' routing sentence, keeping it just short of 5.

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

All PeppolStatus 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