list_productsRetrieve products from the Perly Pay catalog, newest first, with optional active-status filtering and cursor-based pagination to page through results.
List products.
Newest first; pass next_cursor back as cursor for the next page.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | How many objects to return, 1–100. Default 10. | |
| active | No | ||
| cursor | No | `next_cursor` from the previous page. |
Changes observed during successful MCP inspections.
v0.3.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: result ordering (newest first) and the pagination contract. It stops short of describing result shape or page-size behavior default, which matters since there is no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded, with the operational detail (pagination) where an agent will read it. The opening sentence is essentially the title restated and could carry more information, but nothing is padded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Pagination is fully covered, which is the main complexity for a list tool, and annotations cover safety. Combined with the absent description for `active` and no output schema to explain the returned product shape, an agent still lacks enough to use the filter confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
At 67% schema coverage, the two documented parameters (limit, cursor) already carry their own descriptions, and the description's cursor guidance largely restates the schema. The `active` parameter has no description anywhere and is a string enum of "true"/"false" – a filter whose semantics the description never clarifies, leaving the most confusing parameter unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource ("List products"), which is sufficient to separate it from the create/update/retrieve product siblings and from list_prices, list_customers, etc. The name-plus-scope is unambiguous, though the body adds no further scoping detail to sharpen that distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Newest first" plus the cursor round-trip gives an agent the pagination workflow, so usage is at least implied. However there is no guidance on when to choose this over siblings, no mention of the `active` filter as a selection lever, and no stated prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.