Skip to main content
Glama
Pirate Ship MCP Server

Pirate Ship MCP Server

List transactions

list_transactions
Read-onlyIdempotent

Retrieves Pirate Ship balance transactions—label purchases, payments, refunds, and carrier adjustments—with filters for date range, type, and search, plus sorting and pagination.

Instructions

Every charge, payment and refund on the Pirate Ship balance, newest first.

The Reports, Transaction History table: each label purchase, payment, refund and carrier adjustment with its amount in US dollars (negative takes from the balance) and the balance after it. from_date and to_date narrow by day, type by the table's transaction types, search works like its search box.

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": "list_transactions"
  }
}

Input Schema

NameRequiredDescriptionDefault
sortNoOrder by date.newest
typeNoTransaction types as the table shows them, e.g. Label, Payment, Refund.
limitNoRows per page, 1 to 100.
offsetNoRows to skip: the next page starts at offset + limit while it is below total.
searchNoFree text, as in the report's search box.
to_dateNoLast day, YYYY-MM-DD, included.
from_dateNoFirst day, YYYY-MM-DD, in your timezone.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv1.0.4
    • addedInput schema / properties / limit / description
      Added value: +"Rows per page, 1 to 100."
    • addedInput schema / properties / offset / description
      Added value: +"Rows to skip: the next page starts at offset + limit while it is below total."
    • addedInput schema / properties / sort / description
      Added value: +"Order by date."
  2. First observedv0.1.0

TDQS

A3.7/5.0
Behavior4/5

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

Annotations already cover safety (readOnly, idempotent, non-destructive), so the bar is lower, and the description still adds real value: amounts are in US dollars, negative values debit the balance, and each row carries the post-transaction balance, plus default newest-first ordering. It stops short of describing pagination totals or row shape, which the offset schema only partly covers.

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?

Two sentences that lead with the core resource and ordering, then the filter mapping; little waste. The fragment 'The Reports, Transaction History table:' is slightly awkward but functions as an efficient anchor to the UI equivalent.

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 a 7-parameter, all-optional read tool with rich annotations and no output schema, the description supplies enough: what rows are returned, ordering, currency and sign convention, and how the three filter families behave. It could say more about page/total semantics and the full row payload, but nothing critical to calling it is missing.

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 100%, so the schema already documents sort, type, limit, offset, search and both dates with formats and bounds. The description restates the same filtering ideas (date narrows by day, type follows the table's types, search behaves like the search box) without adding syntax or semantics beyond it — baseline 3.

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 description names a concrete resource and scope: every charge, payment, refund and carrier adjustment on the Pirate Ship balance, framed as the Transaction History table. It implicitly positions itself as the superset of list_refunds, list_receipts and list_carrier_adjustments by enumerating those record kinds, but never names a sibling to route away from.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied through the anchor to the Reports > Transaction History table and the note that type/date/search map to that table's controls. There is no explicit when-to-use versus the narrower siblings (list_refunds, list_receipts, list_carrier_adjustments), so an agent must infer that this is the all-in-one view.

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