Skip to main content
Glama
Pirate Ship MCP Server

Pirate Ship MCP Server

List carrier adjustments

list_carrier_adjustments
Read-onlyIdempotent

Retrieve carrier adjustments charged after label use, showing old vs. actual measurements and cost differences for USPS or UPS shipments. Filter by date, status, or carrier to review or dispute charges.

Instructions

Extra charges or credits the carrier made after a label was used, with old and actual package.

The Reports, Carrier Adjustments table: when USPS or UPS measured a package differently from the label (weight, size, package type, zone, ZIP), the old and actual values, the old and new cost and the adjustment in US dollars, and whether it was disputed. dispute_adjustment disputes one by shipment_id.

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_carrier_adjustments"
  }
}

Input Schema

NameRequiredDescriptionDefault
sortNoOrder by date.newest
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.
statusNoAdjustment status as the table shows it.
carrierNoUSPS or UPS.
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.5/5.0
Behavior3/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds domain context about what the rows represent (carrier re-measurement audits after label use) and that adjustments carry a dispute status, but says nothing about volume, latency, or whether historical data has a retention window.

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, front-loaded with the definition of the resource before the report-table detail. There is mild redundancy between 'with old and actual package' and 'the old and actual values', but the enumerated discrepancy fields and the dispute pointer both earn their space.

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 compensates by describing the returned row content (old vs actual measurements, old and new cost, USD adjustment amount, dispute flag), which is exactly what an agent needs to interpret results. It also implies rows carry shipment_id, enabling the follow-up dispute call. Only missing piece is any note on pagination/total semantics, which the schema partially covers.

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 all 8 parameters documented (sort, limit, offset, search, status, carrier, from_date, to_date), so the schema carries parameter meaning fully. The description adds no filtering or format detail beyond the schema and only references shipment_id in the context of the sibling dispute tool. 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?

The description identifies the resource precisely: carrier-issued post-label charges/credits surfaced from the 'Reports, Carrier Adjustments table', with the specific discrepancy dimensions (weight, size, package type, zone, ZIP). It is clearly distinguishable from siblings like list_receipts or list_transactions, though the 'list' verb itself comes from the name/title rather than the prose.

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?

It establishes the data's origin (the Reports > Carrier Adjustments table) and routes the write-side action elsewhere ('dispute_adjustment disputes one by shipment_id'), which is a real boundary hint. However, there is no explicit when-to-use/when-not guidance and no mention of prerequisites such as an account or carrier connection being required.

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