Skip to main content
Glama

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 sector, 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

TableJSON 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 classes (as stored; SIRENE only).
regionNoComma-array of company seat region codes (`BE-BRU,BE-VLG`).
schemeNoComma-array of Peppol identifier schemes.
sectorNoComma-array of 2-digit NACE 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 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.
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 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. Added

TDQS

A4.6/5.0
Behavior5/5

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

Beyond the readOnlyHint annotation, the description discloses two execution sources (rollup vs slice) with their trade-offs, an internal cap of 10,000 participants, degraded responses with null mixes, and the exact semantics of sparse counts (sums below participant_count, _other_ bucket). This is rich, non-obvious behavioral context that an agent needs to set expectations.

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?

The description is long but well-structured with clear section headings ('TWO SOURCES', 'BOUNDED BY DESIGN') and each paragraph adds a distinct piece of essential context. It is front-loaded with the primary purpose and then progressively details behavior. Slightly wordy in places, but the complexity of the endpoint justifies the length.

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?

Despite having no output schema, the description fully explains the response shape: the source field, refreshed_at, degraded flag, participant_count, and the ap_mix bucket. It also covers edge cases like sparse enrichment and the handling of excluded values. An agent can invoke and interpret the result correctly without missing information.

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?

The input schema already covers all 18 parameters with detailed descriptions, examples, and exclusion semantics. The description adds no new parameter-level meaning; it only refers to 'the same names and shapes as GET /v1/participants' and explains that some filters cannot be expressed (leading to degraded mode). Since schema coverage is 100%, the baseline of 3 is appropriate.

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 description opens with a specific verb and resource: 'Get a filtered participant breakdown,' then spells out the exact grouping dimensions (country, entity type, NACE sector, size class, region, Access Point) and the filtered-slice context. It clearly distinguishes this from siblings by emphasizing it's a breakdown rather than raw participant lists or statistics, and even names the fallback endpoint for a whole-network view.

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 gives explicit when-to-use guidance: a request with no narrowing uses the rollup source; a narrow request uses the live slice; a too-wide or unsupported filter returns degraded and instructs callers to fall back to GET /v1/stats/participants. It also names the unsupported filters (doctype, transport_profile, q, host, sub_provider) so an agent can predict behavior.

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