Skip to main content
Glama

List charges

charges_list
Read-only

List charges newest first to review payment activity, filter by status, paid token or network, creation time, or overpayment, and paginate results with a cursor.

Instructions

List this environment's charges, newest first, optionally filtered by status, paid token/network, creation time (since) or isOverpaid. Paginate with limit and the previous page's nextCursor. metadata is left out unless includeMetadata is true.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "charges_list"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoMax items to return per page (1–100, default 20).
sinceNoOnly return charges created at or after this timestamp (filters on `createdAt`, not on when the status last changed). If polling as a fallback for missed webhooks, use a window at least as wide as the longest `expiresIn` your charges use, or you can miss a long-lived charge that changed status outside a narrower window.
tokenNoFilters on `paidWith.token` — the pair actually paid, not accepted.
cursorNoOpaque — pass the previous response's `nextCursor` verbatim to fetch the next page. Never construct or parse this value yourself; its shape is not part of the public contract and may change.
statusNoPayment progress, from the payer side. `pending`: created, nothing received yet. `partially_paid`: some funds received, less than `amount`. `confirmed`: full amount received (or more — see `isOverpaid`). `expired`: `expiresAt` passed with zero funds received. `underpaid`: `expiresAt` passed while `partially_paid`. Every status is reached automatically, on its own timeline — there is no merchant-initiated cancellation. This never reflects whether funds actually reached the merchant — see `settlementStatus` for that.
networkNoFilters on `paidWith.network` — the pair actually paid, not accepted.
isOverpaidNo
includeMetadataNoInclude each charge's free-form `metadata` object (merchant-supplied data, may hold customer details). Omitted unless true.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4/5.0
Behavior4/5

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered; the description adds behavior beyond that: default newest-first ordering, the fact that `metadata` is suppressed unless includeMetadata is true (a meaningful data-omission trait), and the cursor-based pagination model. Rate limits or result-count caps beyond the schema's limit maximum are not discussed.

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?

Three sentences, each earning its place: purpose and ordering first, then filters, then pagination, then the one non-obvious output caveat. No filler and the most important scoping information is front-loaded.

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 eight-parameter, all-optional list tool with no output schema, the description covers selection criteria, ordering and pagination adequately. The only gap is that it never sketches the returned record or the nextCursor envelope, which the agent must infer from the cursor parameter's description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 88%, so the schema already carries the semantics for limit, since, token, cursor, status, network and includeMetadata, including the nuanced distinctions (paid vs accepted pair, status vs settlementStatus). The description largely restates those filters and the pagination mechanics rather than adding new meaning, so the baseline 3 applies.

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 and resource ('List this environment's charges'), plus default ordering ('newest first') and the scope ('this environment's'), which distinguishes it from charges_get and charges_timeline. It does not name a sibling explicitly, so the differentiation comes from the verb rather than explicit routing.

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?

Enumerates the available filters (status, paid token/network, since, isOverpaid) and explains the pagination flow (limit + previous page's nextCursor), giving an agent clear context for how to drive the call. It stops short of stating when to prefer this over charges_check or the timeline tool, or any exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.