Skip to main content
Glama

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

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
keyYesThe provider key (e.g. `c-tickstar`, `o-teamleader-nv-1f3a2b9c`).
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 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 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.
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.
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. Added

TDQS

A4.7/5.0
Behavior5/5

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

Beyond the readOnlyHint annotation, the description discloses the internal 10,000-participant cap, the `degraded: true` response with null mixes, the guarantee of never returning a wrong number or an error, and the sparse-count behavior with un-enriched remainder derivation. This is exactly the kind of behavioral context an agent needs and the annotation alone does not provide.

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?

The lead sentence states the purpose, and the following paragraphs are tightly organized around capability, bounded behavior, and data semantics. Every sentence adds distinct value, and the 'BOUNDED BY DESIGN' section front-loads the most decision-critical behavioral constraint.

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?

For a complex tool with no output schema, the description covers the five breakdowns, degraded mode, null mix behavior, participant_count relationship, sparse enrichment, and fallback strategy. An agent has enough context to call the tool, interpret degraded outcomes, and know what the returned mixes represent.

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?

The input schema already covers 100% of parameters with detailed descriptions, so the baseline is 3. The description adds useful conceptual semantics: filters share names and shapes with `GET /v1/participants`, are scoped to the provider's seats, and lists parameter families that this endpoint cannot express. That elevates it above the baseline.

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 access point roster breakdown') and immediately pins down scope: five roster breakdowns recomputed over a filtered slice. It contrasts this with the stored whole-roster mixes on `GET /v1/aps/{key}`, so an agent can distinguish it from get_access_point and similar siblings without opening schemas.

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?

The description gives clear context for when the filtered breakdown is useful ('so a breakdown stays true while the roster is cut down') and explicitly names `GET /v1/aps/{key}` as the fallback for stored whole-roster mixes. It also lists filters the endpoint cannot express, which helps callers decide whether this tool is appropriate. It stops short of an explicit when-to-use versus sibling-tool statement, but the guidance is strong.

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