Skip to main content
Glama
Pirate Ship MCP Server

Pirate Ship MCP Server

Export shipments

export_shipments
Read-onlyIdempotent

Generates a CSV download link for filtered shipment labels, enabling reporting with one row per label across recipient, tracking, carrier, cost, package, batch, and order data.

Instructions

A CSV of the shipments report with every column, as a download link.

Builds the same spreadsheet as the Export button of Reports, Shipments: one row per label with every column (recipient and address, tracking, carrier and service, cost, package, batch, ship-from, order id, rubber stamps). Takes the filters of list_shipments. Returns a link to the CSV; a filter with no matching labels returns empty true and no link. Large exports can take up to a minute.

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

Input Schema

NameRequiredDescriptionDefault
sortNoOrder by date.newest
batchNoBatch titles.
searchNoFree text, as in the report's search box.
statusNoLabel status as the report shows it, e.g. Printed, Refunded.
carrierNoUSPS or UPS.
to_dateNoLast day, YYYY-MM-DD, included.
from_dateNoFirst day, YYYY-MM-DD, in your timezone.
tracking_statusNoTracking status as the report shows it, e.g. Delivered, In Transit.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv1.0.4
    • addedInput schema / properties / sort / description
      Added value: +"Order by date."
  2. First observedv0.1.0

TDQS

A3.9/5.0
Behavior4/5

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered; the description adds genuinely new behavioral facts beyond that: the return is a link, a no-match filter yields empty=true with no link, and large exports can take up to a minute (a real latency warning). It does not say whether the link expires or how long it stays valid, which is the one meaningful omission.

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?

The lead sentence front-loads both the output format and the download-link nature, then the second sentence gives the content/shape, and the tail covers the edge case and latency. 'Every column' is repeated across the first two sentences, a small redundancy that keeps it short of ideal.

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?

With no output schema, the description does the necessary work of describing the return value (link, empty flag) plus the long-running caveat. What remains unspecified is link lifetime/expiry and any rate or size cap beyond 'up to a minute', which an agent planning a large export would want.

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% with 8 well-documented params (including enum and date formats), so the schema carries parameter semantics. The description only adds that the filter set mirrors list_shipments and that results are 'one row per label', which is mild added value rather than new parameter meaning.

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

Purpose5/5

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

States a specific verb and resource (export shipments as a CSV download link) and characterizes the exact content: one row per label with every column, enumerating the column groups. It also implicitly distinguishes the tool from its data-returning sibling by referencing 'the filters of list_shipments' and calling out that the output is a link, not rows.

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?

The tie-in to list_shipments ('Takes the filters of list_shipments') and the empty-result behavior give the agent a usable mental model, but the description never explicitly says when to prefer this over list_shipments or the sibling export_report. Routing is left to inference from 'csv download link'.

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