Skip to main content
Glama
Sign In

PeppolStatus

by com.peppolstatus
OverviewDiscussionsAdmin

get_access_point_roster_mix

Read-only

Get a filtered access point roster breakdown

The five roster breakdowns of GET /v1/aps/{key} (country, entity type, NACE Rev. 2.1 division, size class, region) recomputed over a FILTERED slice of the roster, so a breakdown stays true while the roster is cut down. The filters are the same names and shapes as GET /v1/participants, scoped to this provider's seats.

BOUNDED BY DESIGN. The breakdowns are computed only when the filtered slice is narrow (under an internal cap of 10,000 participants). A request that narrows on nothing, that carries a filter this endpoint cannot express (doctype, transport_profile, q, host, sub_provider, postcode, provenance, vat_liable), or whose slice is too wide answers degraded: true with every mix null — never a wrong number and never an error. Callers fall back to the stored whole-roster mixes on GET /v1/aps/{key}.

Counts are sparse the same way the stored mixes 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.

A Vendor key (v-<slug>) answers the same question over the Vendor's roster and needs a Market-tier key. seat then selects one Seat the Vendor connects through.

Input Schema

NameRequiredDescriptionDefault
keyYesThe provider key (e.g. `c-tickstar`, `o-teamleader-nv-1f3a2b9c`), or a Vendor key (`v-exact`).
smpNoComma-array of SMP hostnames serving the participant.
seatNoScope the slice to ONE member seat of this provider. A seat that is not a member answers an empty (not degraded) slice. Single-valued.
sizeNoComma-array of company size classes (as stored).
regionNoComma-array of company seat region codes (`NO-32,BE-BRU`).
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 the stored `country_mix` buckets on.
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.
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.
registeredNoRestrict to participants present (`true`) or absent (`false`) in the Peppol Directory.
entity_typeNoComma-array of company legal-form families (`company`, `natural_person`, `association`, `public`).
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. Changed1 schema field 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."
  2. Changed1 schema field changed
    • changedInput schema / properties / key / description
      Previous value: -"The provider key (e.g. `c-tickstar`, `o-teamleader-nv-1f3a2b9c`)."New value: +"The provider key (e.g. `c-tickstar`, `o-teamleader-nv-1f3a2b9c`), or a Vendor key (`v-exact`)."
  3. 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`)."
  4. Added

TDQS

A4.9/5.0
Behavior5/5

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

Annotations only declare readOnlyHint, so the description carries the real behavioral load and does it well: a 10,000-participant cap, `degraded: true` with all-null mixes instead of wrong numbers or errors, sparse counts where every mix except `country_mix` sums below `participant_count`, and a Market-tier key requirement for Vendor keys. This is exactly the beyond-annotations context an agent needs.

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?

Long but front-loaded and organized into a scope sentence, a BOUNDED BY DESIGN block, and a sparse-counts note. Given 15 parameters, a degradation mode, and tiered auth, every sentence carries required information and none is 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?

With no output schema, the description still explains the return shape (five mixes, nulls on degradation, sparse sums below `participant_count`) and the auth tier needed. Nothing an agent needs to call this correctly or interpret the response 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 the schema already documents all 15 parameters and the baseline is 3. The description adds cross-parameter value the schema lacks: the collective filter family mirrors `GET /v1/participants` scoped to this provider's seats, the unsupported filter list, and the Vendor-key-plus-`seat` interaction. It stops short of per-parameter detail, which is correctly left to the schema.

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 (get) and resource (filtered access point roster breakdown) and immediately defines it as the five stored mixes of `GET /v1/aps/{key}` recomputed over a filtered slice. This distinguishes it cleanly from get_access_point (stored whole-roster mixes) and get_participants_mix 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?

Explicitly routes the agent: it names the fallback (stored mixes on `GET /v1/aps/{key}`) and the exact conditions that trigger it (unfiltered request, unsupported filter, slice over the 10,000 cap). It also states the filter family is the same as `GET /v1/participants` and lists the filters this endpoint cannot express, so the agent knows when not to use it.

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