Skip to main content
Glama

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.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
toNoInclusive period end, `YYYY-MM-DD` UTC.
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 category to expand. `newly_matched` and `no_longer_matched` are valid for a Vendor key only; 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."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>`)."
  2. 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"
+}
  3. First observed

TDQS

A4.3/5.0
Behavior5/5

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

Annotations only declare readOnlyHint=true, so this description carries real behavioral weight and delivers: cursor pagination in pages of at most 500 with the next_cursor-until-null loop, ordering by newest observation day first, the Vendor-key mode that adds counterpart_kind, and error behavior (400 for vendor-only categories with a Provider key; empty list for unknown counterpart).

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?

Four sentences, front-loaded with the purpose before pagination and Vendor-key edge cases. Dense but every sentence carries information an agent needs; nothing is padding, though the Vendor-key sentence packs several facts together.

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 7-parameter, cursor-paginated list tool with no output schema, the description covers the loop control (next_cursor/null), ordering, the Provider-vs-Vendor key split, category validity, and counterpart constraints. An agent has everything needed to invoke it correctly.

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 meaning beyond it: `counterpart` is framed as won-from (mover_in) or lost-to (mover_out) and is Valid only for mover categories, and `key` is explained to accept either a Provider key or a Vendor key. This is genuine additive semantics rather than restatement.

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?

States a specific verb+resource ('List participants behind a churn category') and immediately clarifies it is the drill-down producing the participant IDs behind one category count. An agent can distinguish it from count-level siblings like get_access_point_churn, though it never names list_cohort_move_participants, the closest sibling.

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?

Gives real context: it explains the drill-down relationship to a churn category count and the conditions under which `counterpart` applies (mover categories only) and when a Vendor key is used. It stops short of explicitly routing the agent away from any alternative tool, so no exclusions are stated.

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