Skip to main content
Glama
Sign In

PeppolStatus

by com.peppolstatus
OverviewDiscussionsAdmin

list_access_point_churn_participants

Read-only

List participants behind a churn category

The drill-down: the participant IDs behind one churn category count for this Provider over the period, newest observation day first. counterpart narrows a mover category to the participants won from or lost to one Provider. Cursor-paginated in pages of at most 500: follow next_cursor until it is null. A Vendor key (v-<slug>) lists the Vendor's events, also accepts newly_matched and no_longer_matched, and adds counterpart_kind to each item. category takes a comma list, or net for the four net-growth categories: the items come in the order joiner, mover_in, mover_out, leaver (then newly_matched, no_longer_matched), each category newest day first, and every item names its category. day is the short form of from = to = that day. The counts are of participant IDs, not companies: group on company_key to count companies.

Input Schema

NameRequiredDescriptionDefault
toNoInclusive period end, `YYYY-MM-DD` UTC.
dayNoOne UTC day, `YYYY-MM-DD`: the short form of `from` = `to` = `day`. A 400 together with `from` or `to`.
keyYesThe Provider key, or a Vendor key (`v-<slug>`).
fromNoInclusive period start, `YYYY-MM-DD` UTC.
limitNoPage size, clamped to [1, 500]. Defaults to 500 (20 through MCP).
cursorNoOpaque pagination cursor returned as `next_cursor` by the previous page.
categoryYesThe churn categories to expand: one of `joiner`, `mover_in`, `mover_out`, `leaver`, `newly_matched`, `no_longer_matched`, a comma list of them (`joiner,leaver`), or `net` for `joiner,mover_in,mover_out,leaver`. `newly_matched` and `no_longer_matched` are valid for a Vendor key only (and are never in `net`); with a Provider key they are a 400.
counterpartNoFilter to one counterpart Provider key: the Provider the participants were won from (`mover_in`) or lost to (`mover_out`). Allowed with the two mover categories only. For a Vendor key the counterpart can also be a Vendor key. An unknown key returns an empty list.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changed
    • changedInput schema / properties / category / description
      Previous value: -"The churn category to expand. `newly_matched` and `no_longer_matched` are valid for a Vendor key only; with a Provider key they are a 400."New value: +"The churn categories to expand: one of `joiner`, `mover_in`, `mover_out`, `leaver`, `newly_matched`, `no_longer_matched`, a comma list of them (`joiner,leaver`), or `net` for `joiner,mover_in,mover_out,leaver`. `newly_matched` and `no_longer_matched` are valid for a Vendor key only (and are never in `net`); with a Provider key they are a 400."
    • removedInput schema / properties / category / enum
      Removed value: -[
-  "joiner",
-  "mover_in",
-  "mover_out",
-  "leaver",
-  "newly_matched",
-  "no_longer_matched"
-]
    • addedInput schema / properties / category / pattern
      Added value: +"^[a-z_]+(,[a-z_]+)*$"
    • addedInput schema / properties / day
      Added value: +{
+  "description": "One UTC day, `YYYY-MM-DD`: the short form of `from` = `to` = `day`. A 400 together with `from` or `to`.",
+  "format": "date",
+  "type": "string"
+}
  2. Changed4 schema fields changed
    • changedInput schema / properties / category / description
      Previous value: -"The churn category to expand."New value: +"The churn category to expand. `newly_matched` and `no_longer_matched` are valid for a Vendor key only; with a Provider key they are a 400."
    • changedInput schema / properties / category / enum
      Previous value: -[
-  "joiner",
-  "mover_in",
-  "mover_out",
-  "leaver"
-]New value: +[
+  "joiner",
+  "mover_in",
+  "mover_out",
+  "leaver",
+  "newly_matched",
+  "no_longer_matched"
+]
    • changedInput schema / properties / counterpart / description
      Previous value: -"Filter to one counterpart Provider key: the Provider the participants were won from (`mover_in`) or lost to (`mover_out`). Not allowed with `joiner` or `leaver`. An unknown key returns an empty list."New value: +"Filter to one counterpart Provider key: the Provider the participants were won from (`mover_in`) or lost to (`mover_out`). Allowed with the two mover categories only. For a Vendor key the counterpart can also be a Vendor key. An unknown key returns an empty list."
    • changedInput schema / properties / key / description
      Previous value: -"The Provider key."New value: +"The Provider key, or a Vendor key (`v-<slug>`)."
  3. Changed3 schema fields changed
    • addedInput schema / properties / counterpart
      Added value: +{
+  "description": "Filter to one counterpart Provider key: the Provider the participants were won from (`mover_in`) or lost to (`mover_out`). Not allowed with `joiner` or `leaver`. An unknown key returns an empty list.",
+  "type": "string"
+}
    • addedInput schema / properties / cursor
      Added value: +{
+  "description": "Opaque pagination cursor returned as `next_cursor` by the previous page.",
+  "type": "string"
+}
    • addedInput schema / properties / limit
      Added value: +{
+  "default": 500,
+  "description": "Page size, clamped to [1, 500]. Defaults to 500 (20 through MCP).",
+  "maximum": 500,
+  "minimum": 1,
+  "type": "integer"
+}
  4. First observed

TDQS

A4.2/5.0
Behavior5/5

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

Annotations only declare readOnlyHint=true, and the description carries the rest of the load well: page size cap of 500 with the next_cursor loop, result ordering (newest observation day first, per-category ordering for `net`), the fact that a Vendor key adds `counterpart_kind` to each item, that unknown counterpart keys return an empty list, and which inputs produce a 400. This goes well beyond what the annotation declares.

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 the purpose and the drill-down framing, then progressively more specific details. It is dense and somewhat run-on, with heavy product jargon ('mover category', 'Vendor key') packed into a single block, but nearly every clause carries operational information rather than filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 8-parameter, no-output-schema list tool it covers pagination, ordering, error conditions, and some item-level structure (`category` on each item, `counterpart_kind` for Vendor keys). It does not enumerate the remaining per-item fields (e.g. participant ID, observation day, company_key), which the agent must infer, so it is strong but not complete.

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; the description still adds meaning by tying `day` to from=to, explaining that `counterpart` only applies to the two mover categories and how it behaves for a Vendor key, and spelling out the item ordering that `category=net` produces. Some of it restates the schema (comma list, `net` alias), keeping it below 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening line states a specific verb and resource ('List participants behind a churn category') and frames the tool as the drill-down that expands a churn count into participant IDs. The scope ('for this Provider over the period') is stated. It does not explicitly distinguish itself from the sibling list_cohort_move_participants, which is also a participant-level listing, so it falls short of a 5.

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?

It gives clear context for when to reach for it ('the drill-down'), when to use `counterpart` (mover categories only, to narrow to one counterpart Provider), and when to use `category=net` (the four net-growth categories, with their ordering). It offers no explicit exclusion against alternatives like list_cohort_move_participants or get_access_point_churn, so a 4 rather than a 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