Skip to main content
Glama
SMKlog Parcel Shipping Rates

SMKlog Parcel Shipping Rates


Most shipping APIs want a box: length, width, height, weight. People don't have that — they have a thing on the table and a ZIP code to send it to. This server takes the thing.

Describe "a full-size acoustic guitar in its hard case" and it estimates the packed carton, prices it live across three carriers, and hands back services you can actually buy — with the checkout total and, where the carrier publishes one, its own counter price for the same parcel side by side, so you can always show a person both numbers.

What you can ask your assistant

  • "How much to ship a 12 lb box from 07922 to 90011?"

  • "What would it cost to send a full-size acoustic guitar in a hard case from New Jersey to Los Angeles?"

  • "Compare USPS, UPS and FedEx for a 5 lb box, Newark to Chicago — which is cheapest and which is fastest?"

  • "Price a 24 × 18 × 12 in box at 22 lb going to 33101, then give me a link to buy the label."

  • "Where is my package? Tracking 9400111899561234567890."

  • "Did they pay for that label yet? Here is the session id you gave me."

  • "What has a 5 lb box to Denver cost over the last few months?"

  • "Why would a 24 × 18 × 18 in box at 6 lb cost so much to ship?"

  • "When is the last day to mail a gift by USPS for Christmas?"

  • "Can I ship a power bank?"

  • "Was that label refunded?"

Related MCP server: Easyship MCP

Tools

Tool

What it does

get_parcel_quote

Live rates for one parcel from a US origin, domestic or to Canada, the UK, Germany or Australia, across USPS, UPS and FedEx, plus DHL Express to Germany and Australia. Plain-words description → estimated packed box; or pass exact dimensions and weight to skip the estimate. Returns up to five purchasable services with the checkout total (SMKlog fee inside), the carrier's counter price beside it where one is published, and the delivery window.

create_checkout_link

Prices the shipment and returns a payment session: the amount, a handoff URL that opens the SMKlog checkout prefilled with this shipment, and a session_id. The human confirms the contents certification and the carrier-adjustment consent there and pays on Stripe.

get_checkout_status

Where a payment session stands: awaiting_checkout, checkout_started, paid, label_ready (with the tracking number), delivered or refunded. Read from the order record, so it costs no carrier call and never carries names, addresses or emails. Sessions answer for 30 days.

track_parcel

Delivery status, scan events and the carrier's estimated delivery date for a shipment whose label was bought on smklog.com. Not a universal tracker for arbitrary numbers.

get_price_index

The monthly SMKlog parcel price index: six common boxes (1–20 lb) from Newark, NJ to five US cities, repriced through the same live pipeline that prices real shipments. Reading it spends no quote allowance.

get_refund_status

Whether the payment behind a checkout session was refunded, how much and why: not_paid, none, requested, under_review, declined, partially_refunded or refunded. Unused USPS labels are refunded automatically; this tool only reads and never starts a refund.

cancel_checkout_link

Cancels a checkout session the human has not opened yet, so its link stops binding a checkout. Nothing has been paid at that stage, so nothing is refunded; once the human opens checkout the call is refused with session_in_checkout and the checkout stands.

calculate_billable_weight

The weight USPS, UPS and FedEx bill for a box: dimensional weight (L × W × H ÷ 139) against actual weight, rounded as each carrier rounds, and the parcel limits it meets. A calculation only: no carrier call, no quote allowance.

get_holiday_shipping_deadlines

The carriers' own send-by dates for delivery by the 2026 winter holidays (USPS by Dec 25, FedEx by Dec 24), each marked on_track or too_late for today, with the page each date was read from. UPS publishes no fixed dates. Never a guarantee.

get_shipping_restrictions

What SMKlog will not ship and what ships only with conditions, including the lithium battery rules the checkout applies. A policy reference, not a verdict on one item: the quote and the checkout check each item by name.

Things worth knowing before you wire it in

A quote is a real carrier call and costs real money to produce. Call get_parcel_quote once per shipment, not once per variation you are curious about. The server is rate limited per client and will say so plainly rather than silently degrading.

Origin is the United States. Domestic lanes and US-origin exports. A lane that starts somewhere else is out of scope, and the server will tell you instead of inventing a number.

Prices are checkout totals with the SMKlog fee inside. The fee is itemized only on the checkout receipt; what comes back beside a rate is the carrier's own counter price for the same parcel, where one is published — what the person would pay walking into the carrier's counter instead. The total is what they pay.

Parcels only, one label per box. A shipment past parcel limits or described as a pallet or freight load comes back as mode: not_a_parcel with no rates: SMKlog sells parcel labels and does not arrange pallet or freight shipments. quantity counts units of the item: units that fit one box are priced as that box, while units that need more than one box — or a quantity above 1 sent with exact dimensions, which describe one box — come back as mode: multiple_boxes with no rates, so quote each box on its own.

Nothing here buys a label on its own. create_checkout_link produces a URL; a human completes the purchase, certifies the contents and consents to carrier adjustments. An agent cannot spend someone's money through this server.

Connect

{
  "mcpServers": {
    "smklog": {
      "type": "http",
      "url": "https://quote-api.smklog.com/mcp"
    }
  }
}

No key, no OAuth, no signup. All ten tools are open.

Over stdio

For a client that only launches local commands — Claude Desktop, Cursor, an MCP inspector, a Docker-based runner — this repository is a thin stdio bridge to the same endpoint. No dependencies, no build step, no keys:

{
  "mcpServers": {
    "smklog": {
      "command": "npx",
      "args": ["-y", "github:smklog/parcel-shipping-rates-mcp"]
    }
  }
}

Or with Docker:

docker build -t smklog-parcel-shipping-rates-mcp https://github.com/smklog/parcel-shipping-rates-mcp.git
docker run -i --rm smklog-parcel-shipping-rates-mcp

The bridge forwards every JSON-RPC message to https://quote-api.smklog.com/mcp and writes the answer back, one JSON object per line. It also mirrors the 2026-07-28 routing envelope into HTTP headers (MCP-Protocol-Version, Mcp-Method, Mcp-Name) and, on the legacy path, sends the version initialize negotiated, so both protocol eras work through it. If the endpoint cannot be reached it still answers initialize and tools/list from the snapshot shipped here (initialize.json, tools.json), so you can see what is offered; tool calls need the network. npm test drives it end to end.

Configuration

The bridge reads three optional environment variables and nothing else:

Variable

Default

What it does

SMKLOG_MCP_URL

https://quote-api.smklog.com/mcp

Endpoint the bridge forwards to.

SMKLOG_MCP_TIMEOUT_MS

90000 (minimum 1000)

Per-request timeout. A quote is a live carrier call and can take half a minute.

SMKLOG_MCP_DEBUG

unset

1 writes traffic summaries to stderr; stdout stays clean JSON-RPC.

{
  "mcpServers": {
    "smklog": {
      "command": "npx",
      "args": ["-y", "github:smklog/parcel-shipping-rates-mcp"],
      "env": { "SMKLOG_MCP_TIMEOUT_MS": "120000" }
    }
  }
}

Secrets and keys

There are none to configure. The server takes no API key, token or account, and the bridge reads no credentials. Do not put carrier, payment or other API keys into the client config for this server: nothing reads them, and a config file is the wrong place to keep a secret. Carrier and payment credentials live only on the server side.

Data and privacy

  • Quote tools take an item description, postal codes and, optionally, box size and weight. They never ask for street addresses, names, emails or phone numbers. Names, addresses and payment are entered by the person on the smklog.com checkout, not through this server.

  • The description and the box are used to price the parcel with the carriers. A recognized item is kept in our product catalog so the next quote for the same item comes out the same.

  • Each tool call is logged for 30 days: the tool, the item description, the first three characters of each postal code, the destination country, the client software family, the request's country and the outcome. No IP address, full user agent, street address or contact details are stored for this.

  • Rate limits count requests in hourly windows keyed by a one-way SHA-256 hash of the connecting IP (and of IP plus user agent); the address itself is not written.

  • Full policy: https://smklog.com/privacy.

Rated Exemplar on APIs.io (Kin Score by Kin Lane, the API Evangelist): 95.9/100, first of 36,405 rated providers and one of 705 in the Exemplar band, about the top 2% (as of November 1, 2026; the card above shows the live score).

Listed on Smithery and listed in the official MCP registry as com.smklog/parcel-shipping-rates.

Other ways in, if MCP is not your transport: OpenAPI · A2A agent card · API docs · llms.txt

Who runs it

SMKlog sells US shipping labels. The same pricing pipeline that answers this server answers the website — there is no separate "API rate". People who are not using an assistant price and buy the same labels in the shipping calculator. Questions, bugs and odd results: info@smklog.com. Security reports: see SECURITY.md. Changes: CHANGELOG.md.

Available Tools

10 tools
calculate_billable_weightBillable weight of a boxA
Read-onlyIdempotent
Inspect

The weight USPS, UPS and FedEx bill for a box: dimensional weight (L x W x H / 139) against actual weight, rounded as each carrier rounds, and the parcel and USPS limits it meets. Explains why a big light box costs more and how small a box would bill at its real weight. A calculation only: no carrier call, no quote allowance, nothing stored; get_parcel_quote prices the box live.

Parameter rules:

  • length_in, width_in, height_in, weight_lb: all required, above 0, at most 1000.

  • USPS: sides rounded up, 139 only above 1728 cubic inches; UPS and FedEx: nearest inch, every box.

  • Weights round up to a whole pound; USPS prices under 1 lb by the ounce.

  • Limits: parcel 150 lb, 108 in longest side, 165 in length plus girth; USPS 70 lb, 130 in (Ground Advantage) or 108 in (Priority Mail).

NameRequiredDescriptionDefault
width_inYesBox width, inches
height_inYesBox height, inches
length_inYesBox length, inches
weight_lbYesPacked weight, pounds

Output Schema

NameRequiredDescription
hintYesBox-size advice when the box bills 2 lb or more above its weight; else null
noteYesWhat decides: the carrier’s own measurement at acceptance
box_inYesSides rounded up to whole inches, longest first
limitsYes
carriersYesUSPS, UPS and FedEx, in that order
actual_weight_lbYesPacked weight sent, pounds
rounded_weight_lbYesPacked weight rounded up to a whole pound, at least 1
length_plus_girth_inYesLongest side plus twice the other two, sides rounded up

TDQS

A4.9/5.0
Behavior5/5

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds real context beyond them: no live carrier call, nothing persisted, no quote allowance, and the per-carrier rounding and size-threshold rules that determine the result. The USPS 1728-cubic-inch threshold and the 70 lb/130 in vs. 108 in limits are exactly the behavioral details an agent would otherwise get wrong.

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?

Front-loaded with the one-line definition, then a short param-rules block and carrier-rule bullets. Dense but every clause carries a rule or constraint an agent needs; nothing is padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

A four-numeric-input, pure-computation tool with an output schema and full annotation coverage needs exactly this: what is computed, under which carrier rules, what limits apply, and what it does not do. Nothing material is missing.

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

Parameters4/5

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

Schema coverage is 100% and each parameter is a plain dimension or weight, so baseline would be 3. The description adds interpretation the schema cannot: sides are rounded up for USPS vs. nearest inch for UPS/FedEx, the 139 divisor only applies above 1728 cubic inches, and weights round up to whole pounds with USPS pricing sub-pound by the ounce. Minor redundancy in restating required/above 0/at most 1000.

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?

Starts with a precise verb+resource ('The weight USPS, UPS and FedEx bill for a box') and immediately names the computation (dimensional L x W x H / 139 vs. actual, rounded per carrier) plus the limit checks. It is unmistakably distinct from siblings like get_parcel_quote.

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

Usage Guidelines5/5

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

Explicitly bounds usage: 'A calculation only: no carrier call, no quote allowance, nothing stored' and routes to the alternative, 'get_parcel_quote prices the box live.' It also states the questions the tool answers (why a big light box costs more, how small a box would bill at real weight), so when-to-use and when-not-to-use are both covered.

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

get_checkout_statusCheck a checkout sessionA
Read-onlyIdempotent
Inspect

Reports where a create_checkout_link session stands: whether the human opened checkout, paid, and whether the label exists, with the tracking number once it does. Reads SMKlog's own records only: no carrier call, no quote allowance, nothing changes. Poll minutes apart: nothing moves until the human acts.

Statuses, in order: awaiting_checkout, checkout_started, paid (label not bought yet), label_ready (tracking_number present; pass it to track_parcel), delivered, refunded.

Parameter rules:

  • session_id is the as_ plus UUID id from create_checkout_link; no order id, email or quote_id works.

  • A session lives 30 days; an unknown, malformed or expired id answers session_not_found.

  • The answer never carries names, addresses or emails; whoever holds the session_id can read the tracking number.

  • A manual-review request is not a checkout: the status stays awaiting_checkout.

  • 60 checks an hour per client.

NameRequiredDescriptionDefault
session_idYesThe session_id from create_checkout_link.

Output Schema

NameRequiredDescription
nextNoWhat, if anything, the agent should do now
amountNoThe amount the session was anchored to, USD
statusYesStage, in that order
serviceNoThe service the session was anchored to
checkoutNoThe checkout the human started, null while awaiting_checkout
currencyNoISO currency, USD
created_atNoWhen create_checkout_link made the session, ISO 8601
expires_atNoWhen the session stops answering, ISO 8601
session_idYesThe session asked about
quote_reusedNoWhether the session reused a quote_id

TDQS

A4.9/5.0
Behavior5/5

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

Annotations already declare readOnly/idempotent/non-destructive, and the description still adds substantial unannotated behavior: a 60-checks-per-hour client rate limit, a 30-day session lifetime, the session_not_found failure mode, and the privacy property that no names/addresses/emails are returned. These are operational facts an agent cannot derive from structured fields.

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?

Front-loaded with the core answer, then a compact status ladder, then a short bulleted rules block. Every sentence carries a distinct fact; nothing is restated from the schema or annotations.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, yet the description still usefully names the ordered status set and the tracking-number handoff. For a single-parameter polling read tool, nothing an agent needs to call it correctly or interpret the result is missing.

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

Parameters4/5

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

Schema coverage is 100% and the pattern already encodes the as_ prefix, so the baseline is 3. The description earns above baseline by ruling out wrong inputs ('no order id, email or quote_id works') and by mapping the expired/unknown case to session_not_found, which the regex alone cannot convey.

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 ('Reports where a create_checkout_link session stands') and enumerates the exact statuses returned. The tie back to create_checkout_link makes it instantly distinguishable from siblings like track_parcel or get_refund_status.

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

Usage Guidelines5/5

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

Gives explicit when-to-use guidance ('Poll minutes apart: nothing moves until the human acts') and routes the agent forward ('tracking_number present; pass it to track_parcel'). It also names what this is not (no carrier call, a manual-review request is not a checkout), which is exactly the kind of alternative framing that prevents misuse.

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

get_holiday_shipping_deadlinesHoliday shipping deadlinesA
Read-onlyIdempotent
Inspect

The carriers’ own send-by dates for delivery by the 2026 winter holidays: USPS (Ground Advantage, Priority Mail, Priority Mail Express; delivery by Dec 25) and FedEx (Ground Economy, Ground and Home Delivery by days in transit, Express Saver, 2Day, Overnight; delivery by Dec 24), each marked on_track or too_late for today in New York, with the page each date was read from. UPS publishes no fixed dates, and the answer says so. Contiguous US only; never a guarantee and never an SMKlog estimate. No carrier call, no quote allowance.

Parameter rules:

  • No parameters.

  • After Dec 24, 2026 the answer says the season is over and lists no dates.

  • For a real lane and service, get_parcel_quote returns each service’s delivery estimate.

NameRequiredDescriptionDefault

No parameters

Output Schema

NameRequiredDescription
noteYesWhat the dates are and are not
todayYesToday in New York (America/New_York), YYYY-MM-DD
seasonYesWhich season the dates are for
carriersYesUSPS, FedEx and UPS
coverageYesWhich lanes the dates are for
season_overYesTrue after Dec 24, 2026; carriers is then empty

TDQS

A4.5/5.0
Behavior5/5

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

Annotations already declare readOnly/idempotent/openWorld=false, and the description still adds substantial behavior: each date is marked on_track or too_late relative to 'today in New York', source pages are returned, results are not guarantees, and after Dec 24, 2026 the answer reports the season is over with no dates. It also clarifies that no carrier call or quote allowance is consumed, which is real operational context beyond the hints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core purpose is front-loaded and dense with useful detail, but the run-on carrier enumeration plus jargon-ish fragments ('No carrier call, no quote allowance', 'never an SMKlog estimate') cost readability. Some clauses restate what the opening already established.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a no-parameter, read-only lookup with an output schema, the definition covers everything an agent needs: coverage boundaries, carrier gaps, timezone for the on_track/too_late logic, seasonal expiry, and the sibling to use for actual lane quotes. Return shape is correctly left to the output schema.

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

Parameters4/5

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

Zero parameters, so baseline is 4; the description goes slightly further by devoting a 'Parameter rules' section to the absence of inputs and the time-based edge behavior. That is behavior rather than parameter meaning, so no credit above baseline.

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?

Names a specific resource (carriers' own send-by dates for the 2026 winter holidays) and enumerates the exact carrier/service coverage: USPS Ground Advantage/Priority/Express by Dec 25, FedEx Ground Economy/Ground/Express Saver/2Day/Overnight by Dec 24. It also explicitly carves out what it is not ('never an SMKlog estimate') and separates itself from sibling get_parcel_quote, so an agent can pick it without opening the schema.

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?

Gives a clear routing rule to the alternative: 'For a real lane and service, get_parcel_quote returns each service's delivery estimate.' It also states scope limits (contiguous US only) and an exclusion (UPS publishes no fixed dates). It lacks an explicit 'use when the user asks X' trigger sentence, but the context is unambiguous.

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

get_parcel_quoteGet live parcel shipping rates from a US originA
Read-only
Inspect

Live parcel rates from a US origin: USPS, UPS, FedEx; DHL Express to DE and AU. Describe the item to estimate the box, or give exact dimensions and weight. Up to five services, each a total with the SMKlog fee inside (itemized only on the checkout receipt). To buy on smklog.com: quote_id to create_checkout_link. Typical prices: get_price_index (free).

Parameter rules:

  • weight_lb, length_in, width_in, height_in count only as a set of four above zero, else the box is estimated.

  • One label per box: units that fit one box are priced as that box; more boxes or a quantity above 1 sent with exact dimensions: multiple_boxes.

  • Over 150 lb, 108 in longest side or 165 in length plus girth, or pallet or freight: mode not_a_parcel.

  • product: the item, up to 200 characters; a bare route, weight or question: product_not_recognized.

  • from_zip: a real 5-digit US ZIP, else invalid_us_zip.

  • to_country: US, CA, GB, DE or AU, else international_unsupported_online; to_zip follows it.

  • 80 calls an hour per client.

NameRequiredDescriptionDefault
to_zipYesA 5-digit ZIP for the US, else the country's postal code, e.g. M5V 2T6 (Toronto), SW1A 1AA (London).
productYesPlain-words item description, e.g. "65 inch flat screen TV in original box".
from_zipYesOrigin US ZIP code, 5 digits.
quantityNoHow many of the item ship together.
width_inNoPacked box width, inches.
height_inNoPacked box height, inches.
length_inNoPacked box length, inches.
weight_lbNoPacked weight, pounds.
to_countryNoTwo-letter destination country: US (default), CA, GB, DE, AU.US

Output Schema

NameRequiredDescription
modeNoparcel_label_ready when rates are listed; otherwise not_a_parcel, multiple_boxes or parcel_restricted
ratesYesUp to five services. Not cheapest first: ranked by checkout total in cents plus 175 per business day in transit (30 when none is quoted), lowest first; a rate with a carrier counter price may lead a near-tie within 50 cents or 2 percent. Sort by amount yourself for the cheapest.
packageNoThe packed box the rates were computed for
quote_idNoValid 15 minutes; pass it to create_checkout_link to skip a second carrier call. Null when no rate came back or it could not be stored.

TDQS

A4.9/5.0
Behavior5/5

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

Annotations already declare read-only, open-world reading, so the description goes further: it discloses the 80 calls/hour rate limit, that up to five services are returned, that the SMKlog fee is baked into each total and itemized only on the receipt, and the specific error codes for bad input. That is behavior an agent cannot infer from annotations.

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 is front-loaded with purpose and the buyer/price-index routing, and the bulleted parameter rules are scannable. It is dense but nearly every clause carries an actionable rule; the telegraphic phrasing (e.g. 'a bare route, weight or question: product_not_recognized') costs a little readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, the description correctly avoids restating return shapes and instead spends its length on inputs, thresholds, error modes, and rate limits. For a nine-parameter quote tool with geographic restrictions, nothing an agent needs to call it correctly appears to be missing.

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

Parameters5/5

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

Despite 100% schema coverage, the description adds genuine conditional semantics the schema lacks: the four dimension fields only apply as a set all above zero or the box is estimated, one label per box with quantity >1 plus dimensions escalating to multiple_boxes, the 150 lb / 108 in / 165 in girth thresholds, the 200-character product limit, and the real-ZIP and country enum constraints.

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?

The opening sentence gives a specific verb and resource (live parcel rates) plus scope (US origin), names the carriers (USPS, UPS, FedEx) and the DHL country limits. It also distinguishes itself from siblings by pointing to create_checkout_link and get_price_index, so an agent can choose correctly without reading schemas.

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

Usage Guidelines5/5

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

It explicitly routes the agent: use this tool for live rates, get_price_index for typical prices (free), and create_checkout_link with the returned quote_id to buy. It also defines when NOT to use it, by mapping oversized/pallet/freight cases to mode not_a_parcel and multi-box cases to multiple_boxes.

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

get_price_indexUS parcel shipping price indexA
Read-onlyIdempotent
Inspect

The SMKlog parcel shipping price index: a monthly repriced basket of six common boxes (1 to 20 lb) shipped from Newark, NJ to five US cities, quoted through the same live USPS, UPS and FedEx pipeline that prices real shipments. Returns the cheapest purchasable service per box and lane with every rate behind it, plus basket averages. Reference data for questions like "what does shipping a shoebox cost in the US right now" — reading it spends no quote allowance. For a price on a specific shipment, call get_parcel_quote instead. Parameter rules: month names one published issue as YYYY-MM; issues exist from 2026-07 onward, one per month, and omitting month returns the newest. A month with no issue answers issue_not_found together with available_months, so one miss lists every valid value; anything not shaped YYYY-MM answers invalid_month. Every issue prices the same boxes and lanes, so two months compare cell for cell.

NameRequiredDescriptionDefault
monthNoIssue month as YYYY-MM. Omit for the newest published issue.

Output Schema

NameRequiredDescription
pageNoThe published issue page on smklog.com
cellsYesOne entry per box and destination
labelNoIssue month spelled out, e.g. "August 2026"
monthYesIssue month, YYYY-MM
originNoOrigin of every lane, Newark NJ (07102)
captured_onYesThe date every price in this issue was captured
methodologyNoHow the numbers are produced
carrier_winsNoHow many cells each carrier priced cheapest
basket_averageNoMean of the cheapest rate across all thirty cells, USD

TDQS

A5/5.0
Behavior5/5

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

Annotations already mark the tool as read-only, idempotent, and non-destructive, and the description adds valuable behavioral detail: reading spends no quote allowance, invalid month shapes return invalid_month, and missing issues return issue_not_found with available_months. It also states that every issue is directly comparable month-over-month, which is useful operational context.

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?

The description is dense but every sentence earns its place: definition, output, use case, alternative, and parameter rules are all front-loaded in a logical order. There is no filler or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only reference tool with one optional parameter and an output schema, the description covers purpose, use case, alternatives, parameter behavior, error semantics, and comparability. Nothing an agent needs to invoke it correctly is missing.

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

Parameters5/5

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

Schema coverage is 100%, but the description goes far beyond it: it specifies the YYYY-MM format, the default when month is omitted, the earliest available issue (2026-07), one-issue-per-month granularity, and the exact error responses for invalid or nonexistent months. This fully compensates for any ambiguity in the schema alone.

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?

The description names a specific resource (SMKlog US parcel shipping price index), defines its scope (six boxes, 1-20 lb, Newark to five US cities), and states the output. It also distinguishes itself from get_parcel_quote, so an agent can tell them apart without opening schemas.

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

Usage Guidelines5/5

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

It explicitly says this is reference data for questions like US shipping costs, notes that reading spends no quote allowance, and directs callers to get_parcel_quote for a specific shipment. This is clear when-to-use and when-not-to-use guidance with a named alternative.

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

get_refund_statusRefund status of a checkout sessionA
Read-onlyIdempotent
Inspect

Says whether the payment behind a create_checkout_link session was refunded, how much and why. Status: not_paid (nothing to refund), none (paid, not refunded), requested (a refund is under way), under_review (an unused non-USPS label, decided by an operator), declined (the label was scanned, so the carrier refused the refund), partially_refunded or refunded; with amount_paid, amount_refunded, reason (unused_label: the automatic refund of a never-scanned label; other) and the refund policy in force. Unused USPS labels are refunded automatically; this tool only reads, it never starts a refund. SMKlog records only: no carrier call, no quote allowance.

Parameter rules:

  • session_id is the as_ plus UUID id from create_checkout_link; no order id or email works.

  • An unknown, malformed or expired id answers session_not_found.

  • It reports on the checkout get_checkout_status reports.

  • No names, addresses, emails or card details.

  • 60 checks an hour per client, shared with get_checkout_status.

NameRequiredDescriptionDefault
session_idYesThe session_id from create_checkout_link.

Output Schema

NameRequiredDescription
nextYesWhat, if anything, the agent should do now
policyYesThe refund policy in force
reasonNo
statusYes
currencyYesISO currency, USD
order_idNoSMKlog order id, the reference for support; null before checkout
session_idYesThe session asked about
amount_paidYesUSD; 0 while not_paid
requested_atNoWhen the automatic unused-label refund was requested, ISO 8601
amount_refundedYesUSD refunded so far

TDQS

A4.6/5.0
Behavior5/5

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

Goes well beyond the annotations: discloses a 60-checks-per-hour client limit shared with get_checkout_status, explains that it reads SMKlog records only with no carrier call or quote allowance, and confirms no names, addresses, emails or card details are returned. It also explains operator-driven states (under_review, declined after a scan) that an agent could not infer from the annotation set.

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?

Front-loaded with purpose, then a compact status enumeration, then a short parameter-rules block, with no filler sentences. The status enumeration is long and partially overlaps the output schema, which is the main redundancy, but each line still carries information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter read tool with a rich annotation set and an output schema, this covers the remaining gaps: rate limits, error conditions, data exposure, relationship to sibling tools, and the meaning of each refund state. An agent could call this correctly and interpret the result without further context.

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

Parameters4/5

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

Schema coverage is already 100%, but the description still adds meaning: the id must be the as_ plus UUID value from create_checkout_link, no order id or email works, and unknown/malformed/expired ids return session_not_found. That error behavior and provenance are not in the schema.

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: it says whether the payment behind a create_checkout_link session was refunded, how much and why. It also distinguishes itself from the sibling get_checkout_status by explicitly noting it reports on the checkout that tool reports on.

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?

Clear usage context: it only reads and never starts a refund, so an agent knows not to reach for it to initiate one, and it names get_checkout_status as the companion call. It stops short of explicitly naming an alternative for starting a refund, so the when-not routing is implied rather than spelled out.

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

get_shipping_restrictionsShipping restrictions and battery rulesA
Read-onlyIdempotent
Inspect

What SMKlog will not ship and what ships only with conditions: prohibited categories (weapons, drugs, counterfeit goods, money and valuables, living and perishable contents, dangerous goods, controlled exports), restricted ones (batteries, medicine, chemicals and aerosols, regulated natural products, age-restricted goods), the lithium battery rules the checkout applies (installed: UN3481 mark, ground; power banks: UN3480, ground only, up to 100 Wh and 5 lb; larger or lithium-metal batteries reviewed by hand), how to describe an item, and the international rules. The policy published at smklog.com/shipping-restrictions. No carrier call, no quote allowance.

Parameter rules:

  • No parameters.

  • A policy reference, not a verdict on one item: get_parcel_quote and the checkout check each item, by name too.

  • The lists are examples, not complete; carrier and destination rules can be stricter.

NameRequiredDescriptionDefault

No parameters

Output Schema

NameRequiredDescription
summaryYes
batteriesYesThe lithium battery rules, case by case
prohibitedYesCategories refused outright, with examples
restrictedYesCategories that ship only with conditions, or that the online checkout may refuse
policy_pageYesThe published policy
descriptionsYesHow to describe an item
internationalYesDestinations and the customs declaration
how_smklog_checksYesWhen SMKlog checks an item
restricted_handlingYesWhat a restricted item may need
carrier_rules_controlYesWho decides acceptance

TDQS

A4.6/5.0
Behavior4/5

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

The annotations already declare this to be a read-only, idempotent, non-destructive, closed-world operation, so the safety profile is covered. The description then adds context that the annotations cannot: this is a static published policy, it makes no carrier call and returns no quote, and the listed categories are examples rather than a complete or authoritative set, since carrier and destination rules may be stricter. The one thing it does not say is explicit guidance on how to combine this policy with a per-item check, but the usage section largely covers that.

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 content is front-loaded: the opening clause says what the tool returns, and the trailing sentences add the important qualifiers. The list of categories is long but it is the substance an agent needs for judgment. The fragment 'The policy published at smklog.com/shipping-restrictions.' is slightly awkward phrasing, and one long sentence carries many clauses, but no sentence is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Because the tool is parameterless and has an output schema, the description does not need to cover return shape or parameter behavior. The context around annotations, mutation profile, non-exhaustiveness of the lists, and sibling routing is complete. An agent can confidently decide when to call this tool and what to expect from it.

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

Parameters4/5

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

This tool has zero parameters, so the schema is already complete, and the baseline for a parameterless tool is 4 or higher. The description's 'No parameters' line is redundant with the schema rather than informative, so it does not earn a higher score. There is no parameter semantics to add and nothing misleading to subtract.

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?

The description states a specific resource with a specific scope: the shipping restrictions and battery rules that SMKlog applies. It names the concrete content an agent will receive: prohibited categories, restricted categories, lithium-battery rules (UN3481/UN3480 and the Wh/lb limits), and international rules. It also distinguishes itself from its siblings: quote and checkout tools give per-item verdicts, while this tool gives the policy.

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

Usage Guidelines5/5

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

The description gives both the positive condition and the exclusion. It says to use this tool for the policy, not for an item-level verdict, and it names get_parcel_quote and the checkout path as the alternatives for that job. The line 'No carrier call, no quote allowance' clears up a likely false expectation. Nothing about when to use it is left to inference.

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

track_parcelTrack a SMKlog shipmentA
Read-onlyIdempotent
Inspect

Track a shipment whose label was bought on smklog.com, by carrier tracking number: the current status, the latest scan events (newest first, up to eight) and the estimated delivery date when the carrier gives one. SMKlog labels only: not a universal tracker, so another seller's number answers not-found. Spends no quote allowance. Once a create_checkout_link session reaches label_ready, get_checkout_status hands back this number.

Parameter rules:

  • tracking_number is the only key; no order id or email.

  • It is matched after removing spaces and hyphens, ignoring case.

  • Typical shapes: USPS 20 to 22 digits (13 characters ending in US for international), UPS 1Z plus 16 characters, FedEx 12 to 22 digits.

  • Under 6 characters after cleanup: tracking_number_required. A number SMKlog never sold: 404 tracking_not_found.

NameRequiredDescriptionDefault
tracking_numberYesCarrier tracking number from the SMKlog receipt or label page

Output Schema

NameRequiredDescription
eventsYesScan events, newest first, up to eight
trackingYes

TDQS

A4.9/5.0
Behavior5/5

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

Annotations already declare read-only, idempotent and open-world, and the description still adds material behavior: no quote allowance is consumed, scan events are capped at eight and ordered newest-first, and the not-found path returns 404 tracking_not_found. These are operational facts an agent cannot infer from the annotations or schema.

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 scope statement and the exclusion are front-loaded, and the parameter rules are cleanly bulleted with no filler. The opening sentence is long, stacking scope, return shape and event ordering into one clause chain, which slightly slows scanning but wastes nothing.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, return values need not be explained, and the description still covers scope, input normalization, quota cost, and error conditions. For a single-parameter read tool this leaves nothing an agent needs missing before calling it.

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

Parameters5/5

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

Schema coverage is 100%, so the baseline would be 3, but the description adds real meaning beyond the schema: normalization rules (spaces and hyphens stripped, case ignored), typical carrier shapes, and a minimum-length threshold that triggers tracking_number_required. An agent can pre-validate input rather than learn the rules from an error.

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 ("Track a shipment whose label was bought on smklog.com, by carrier tracking number") and immediately enumerates what comes back: current status, latest scan events, estimated delivery date. It also draws an explicit boundary against universal trackers, so an agent can distinguish it from any sibling without opening a schema.

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

Usage Guidelines5/5

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

Names the negative case explicitly ("SMKlog labels only: not a universal tracker, so another seller's number answers not-found") and describes the upstream path that produces the input ("Once a create_checkout_link session reaches label_ready, get_checkout_status hands back this number"). That is explicit when-to-use plus a named alternative source, which is the top of the scale.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 7 tool updatesv1.5.0
    • Addedcalculate_billable_weight
    • Addedcancel_checkout_link
    • Changedcreate_checkout_link2 fields changed
      • changedInput schema / properties / quantity / description
        Previous value: -"Identical parcels in this shipment. Default 1."New value: +"How many of the item ship together. Default 1."
      • changedInput schema / properties / service / description
        Previous value: -"Service to anchor the amount to, e.g. \"USPS Ground Advantage\". Cheapest when omitted; the human can still pick any service on the page."New value: +"Service to anchor the amount to, e.g. \"USPS Ground Advantage\". Omitted or unmatched, the amount anchors the quote's first rate, top of the best-value ranking rather than the cheapest; the human can still pick any service on the page."
    • Addedget_holiday_shipping_deadlines
    • Changedget_parcel_quote14 fields changed
      • changedInput schema / properties / from_zip / description
        Previous value: -"Origin US ZIP code, 5 digits. The origin is always in the United States."New value: +"Origin US ZIP code, 5 digits."
      • changedInput schema / properties / quantity / description
        Previous value: -"Identical parcels in this shipment. Default 1."New value: +"How many of the item ship together."
      • changedInput schema / properties / to_zip / description
        Previous value: -"Destination postal code: a 5-digit ZIP for the US, or the destination country's own postal code, e.g. M5V 2T6 for Toronto or SW1A 1AA for London."New value: +"A 5-digit ZIP for the US, else the country's postal code, e.g. M5V 2T6 (Toronto), SW1A 1AA (London)."
      • changedInput schema / properties / weight_lb / description
        Previous value: -"Packed weight, pounds. Decimals allowed."New value: +"Packed weight, pounds."
      • changedOutput schema / description
        Previous value: -"Live rates for the shipment. Empty rates with mode \"freight_manager\" means a person prices it."New value: +"Live rates; when rates is empty, mode says why."
      • changedOutput schema / properties / mode / description
        Previous value: -"Quote mode; \"freight_manager\" routes to a human review"New value: +"parcel_label_ready when rates are listed; otherwise not_a_parcel, multiple_boxes or parcel_restricted"
      • changedOutput schema / properties / quote_id / description
        Previous value: -"Handle to this quote, good for 15 minutes. Pass it to create_checkout_link as quote_id and that call spends no second carrier call. Null when no rate came back, or when the handle could not be stored."New value: +"Valid 15 minutes; pass it to create_checkout_link to skip a second carrier call. Null when no rate came back or it could not be stored."
      • changedOutput schema / properties / rates / description
        Previous value: -"Purchasable services, cheapest first"New value: +"Up to five services. Not cheapest first: ranked by checkout total in cents plus 175 per business day in transit (30 when none is quoted), lowest first; a rate with a carrier counter price may lead a near-tie within 50 cents or 2 percent. Sort by amount yourself for the cheapest."
      • changedOutput schema / properties / rates / items / properties / amount / description
        Previous value: -"Checkout total, USD"New value: +"Checkout total, USD, SMKlog fee inside"
      • removedOutput schema / properties / rates / items / properties / carrier_amount
        Removed value: -{
        -  "description": "Negotiated carrier cost, USD",
        -  "type": "number"
        -}
      • changedOutput schema / properties / rates / items / properties / delivery_days / description
        Previous value: -"Business days in transit when the carrier quotes one"New value: +"Business days in transit, if quoted"
      • changedOutput schema / properties / rates / items / properties / delivery_estimated_date / description
        Previous value: -"Estimated delivery date when quoted"New value: +"Estimated delivery date, if quoted"
      • changedOutput schema / properties / rates / items / properties / retail_amount / description
        Previous value: -"Carrier retail counter price, USD; 0 when not published"New value: +"Carrier counter price, USD; 0 when not published"
      • removedOutput schema / properties / rates / items / properties / service_fee
        Removed value: -{
        -  "description": "SMKlog fee, USD",
        -  "type": "number"
        -}
    • Addedget_refund_status
    • Addedget_shipping_restrictions
  2. 5 tool updatesv0.1.0
    • First observedcreate_checkout_link
    • First observedget_checkout_status
    • First observedget_parcel_quote
    • First observedget_price_index
    • First observedtrack_parcel

TDQS

A4.7/5.0

Scored across 10 tools

Disambiguation5/5

Each tool targets a distinct action in the shipment lifecycle (quote, checkout creation, cancellation, status, refund status, tracking) or a distinct reference domain (billable weight, holiday deadlines, restrictions, price index). The boundary between get_checkout_status and get_refund_status is explicitly clarified, and get_price_index explicitly defers to get_parcel_quote. No two tools appear interchangeable.

Naming Consistency5/5

All ten names are snake_case with a clear verb_noun shape (get_parcel_quote, create_checkout_link, cancel_checkout_link, track_parcel, calculate_billable_weight). The convention is uniform throughout, with track_parcel the only minor omission of 'get' and still fully readable.

Tool Count5/5

Ten tools is well within the ideal 3-15 band and each one maps to a real operation or reference lookup. Nothing looks redundant or padded.

Completeness4/5

The purchase lifecycle (quote, checkout, cancel, status, track, refund status) is well covered, and reference tools fill out the surface. The main gap is that refunds cannot be initiated and shipped details cannot be amended, since get_refund_status and get_checkout_status are strictly read-only, though the descriptions frame this as by design.

Maintenance

ActivityActive
ResponsivenessLimited data

Related MCP Connectors

Related MCP Servers

  • A
    license
    A
    quality
    D
    maintenance
    Manage shipping workflows by creating labels, tracking packages, and scheduling carrier pickups. Compare live rates from major carriers like FedEx and UPS to optimize costs for every shipment. Organize logistical operations with a centralized address book and detailed shipping analytics.
    18
    9 npm
    1
    MIT
  • A
    license
    Not graded
    quality
    D
    maintenance
    Enables AI agents to manage global shipping operations, including rate comparison, shipment creation, label purchasing, tracking, pickup scheduling, address validation, billing, and analytics, via natural language.
    32 npm
    MIT