SMKlog Parcel Shipping Rates
This server lets an assistant quote live US-origin parcel shipping rates, create a human checkout link for a shipping label, track SMKlog shipments, query a parcel price index, and check checkout/label status.
Get live USPS, UPS, and FedEx rates—plus DHL Express to Germany and Australia—for one parcel from a US ZIP to the US, Canada, UK, Germany, or Australia, using plain-language item descriptions or exact dimensions/weight.
Create a checkout session and handoff URL for a chosen shipment, optionally reusing a
quote_id; it never charges or buys the label itself.Track a shipment whose label was bought on SMKlog by tracking number, returning delivery status, latest scans, and estimated delivery.
Read the monthly SMKlog US parcel price index for six common box sizes across five US cities, including all rates and basket averages.
Check a checkout session’s status through awaiting checkout, payment, label creation, tracking number, delivery, or refund.
Key limits: origin must be in the US; only supported destinations are accepted; freight/oversize/multi-box cases go to manual review; tracking only works for SMKlog labels.
Provides live DHL Express parcel shipping rate quotes from the US to Germany and Australia, including purchasable services, checkout totals, carrier costs, and delivery windows.
Provides live FedEx parcel shipping rate quotes for US domestic and selected international lanes, including purchasable services, checkout totals, carrier costs, and delivery windows.
Provides live UPS parcel shipping rate quotes for US domestic and selected international lanes, including purchasable services, checkout totals, carrier costs, and delivery windows.
Provides live USPS parcel shipping rate quotes for US domestic and selected international lanes, including purchasable services, checkout totals, carrier costs, and delivery windows.
This server has a remotely hosted endpoint. Open its connector listing for connection details, authentication requirements, and setup instructions:
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 |
| 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. |
| Prices the shipment and returns a payment session: the amount, a handoff URL that opens the SMKlog checkout prefilled with this shipment, and a |
| Where a payment session stands: |
| 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. |
| 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. |
| Whether the payment behind a checkout session was refunded, how much and why: |
| 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 |
| 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. |
| The carriers' own send-by dates for delivery by the 2026 winter holidays (USPS by Dec 25, FedEx by Dec 24), each marked |
| 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-mcpThe 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 |
|
| Endpoint the bridge forwards to. |
|
| Per-request timeout. A quote is a live carrier call and can take half a minute. |
| unset |
|
{
"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 toolscalculate_billable_weightBillable weight of a boxARead-onlyIdempotentInspect
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).
| Name | Required | Description | Default |
|---|---|---|---|
| width_in | Yes | Box width, inches | |
| height_in | Yes | Box height, inches | |
| length_in | Yes | Box length, inches | |
| weight_lb | Yes | Packed weight, pounds |
Output Schema
| Name | Required | Description |
|---|---|---|
| hint | Yes | Box-size advice when the box bills 2 lb or more above its weight; else null |
| note | Yes | What decides: the carrier’s own measurement at acceptance |
| box_in | Yes | Sides rounded up to whole inches, longest first |
| limits | Yes | |
| carriers | Yes | USPS, UPS and FedEx, in that order |
| actual_weight_lb | Yes | Packed weight sent, pounds |
| rounded_weight_lb | Yes | Packed weight rounded up to a whole pound, at least 1 |
| length_plus_girth_in | Yes | Longest side plus twice the other two, sides rounded up |
TDQS
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.
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.
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.
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.
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.
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.
cancel_checkout_linkCancel a checkout sessionADestructiveIdempotentInspect
Cancels a create_checkout_link session the human has not opened yet: its handoff link stops binding a checkout, and get_checkout_status answers session_cancelled from then on. Nothing has been paid at that stage, so nothing is refunded and no human is needed. Once the human opens checkout the call is refused with session_in_checkout and the checkout stands: an unpaid one expires on its own, a paid one is refunded by SMKlog support and get_refund_status follows it. Idempotent: cancelling a cancelled session answers the same. No carrier call, no quote allowance.
Parameter rules:
session_id is the as_ plus UUID id from create_checkout_link.
An unknown, malformed or expired id answers session_not_found.
From checkout_started on: session_in_checkout, and nothing changes.
To try again, call create_checkout_link for a new session.
60 calls an hour per client, shared with get_checkout_status.
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | Yes | The session_id from create_checkout_link. |
Output Schema
| Name | Required | Description |
|---|---|---|
| next | No | What, if anything, the agent should do now |
| amount | No | The amount the session was anchored to, USD |
| status | Yes | |
| service | No | The service the session was anchored to |
| checkout | No | Always null: no checkout was opened |
| currency | No | ISO currency, USD |
| created_at | No | When create_checkout_link made the session, ISO 8601 |
| expires_at | No | When the session would have stopped answering, ISO 8601 |
| session_id | Yes | The session cancelled |
| cancelled_at | Yes | When it was cancelled, ISO 8601 |
| quote_reused | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Well beyond the annotations, it discloses the full state machine: the handoff link stops binding, get_checkout_status then answers session_cancelled, unpaid sessions simply expire while paid ones are refunded via SMKlog support tracked by get_refund_status. It also discloses the idempotency semantics and a concrete rate limit (60 calls an hour per client, shared with get_checkout_status). The destructiveHint=true annotation is not contradicted — the description explains that destruction is limited to the link binding, with no funds moved.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The core behavior is front-loaded in the first two sentences and the parameter rules are cleanly separated into a bulleted block, so structure is strong. It runs long for a single-parameter tool, and the payment/refund clause pair takes a moment to resolve as describing two different states rather than one contradiction.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be explained, and the annotations cover the safety profile. What remains — preconditions, refusal codes, retry procedure, refund follow-up, and throughput limits — is all present, leaving nothing an agent needs missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: the id is "the as_ plus UUID id from create_checkout_link" and the error taxonomy for unknown, malformed, or expired ids is session_not_found. It stops short of explaining the pattern's 8-80 character length, but the error behavior is the more useful addition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource ("Cancels a create_checkout_link session the human has not opened yet") and immediately distinguishes the scope from its siblings by naming create_checkout_link and get_checkout_status. An agent can tell exactly what this does 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states the precise precondition for success (session not yet opened), the refusal condition with the exact error code (session_in_checkout once checkout_started), and the explicit recovery path ("call create_checkout_link for a new session"). It also names the downstream diagnostic tool get_checkout_status as the observer of session_cancelled.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_checkout_linkCreate a payment session for a shipping labelAInspect
Turns a decided shipment into a payment session: the amount and a handoff URL to prefilled SMKlog checkout. Pass quote_id from get_parcel_quote: its price is reused, no second carrier call. Keep the returned session_id for get_checkout_status. It never charges: the human confirms contents and consents, then pays on the page.
Side effects: writes a 30-day session record; not idempotent, two calls make two sessions. No session for a non-parcel, several boxes, or an installed lithium battery crossing a border.
Parameter rules:
A valid quote_id overrides product, from_zip, to_zip, to_country and quantity; service still applies.
An expired quote_id reprices from the fields, or fails with missing_required_fields without them.
service is a case-insensitive fragment of the display name; no match anchors the quote's first rate, not always the cheapest.
from_zip: 5-digit US ZIP; to_zip follows to_country (US, CA, GB, DE, AU).
International: customs on the page; the recipient pays duty.
| Name | Required | Description | Default |
|---|---|---|---|
| to_zip | No | Destination postal code: a 5-digit ZIP for the US, or the destination country's own postal code. Required unless quote_id is given. | |
| product | No | Plain-words item description. Required unless quote_id is given. | |
| service | No | 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. | |
| from_zip | No | Origin US ZIP code, 5 digits. Required unless quote_id is given. | |
| quantity | No | How many of the item ship together. Default 1. | |
| quote_id | No | The quote_id returned by a previous get_parcel_quote call. Valid for 15 minutes. | |
| to_country | No | Two-letter destination country: US (default), CA, GB, DE, AU. | US |
Output Schema
| Name | Required | Description |
|---|---|---|
| note | No | Standing caveats: live quote, human confirms consents and pays |
| amount | Yes | Live-quoted checkout total for the anchored service, USD |
| intent | Yes | Always "session" — this tool never charges |
| method | No | Payment rails behind the checkout, e.g. stripe, card |
| service | No | The service the amount is anchored to |
| currency | Yes | ISO currency, USD |
| session_id | No | Handle for get_checkout_status, shaped as_ plus a UUID, good for 30 days. Null only when the session record could not be stored. |
| handoff_url | Yes | Opens the SMKlog checkout prefilled with this shipment |
| quote_reused | No | True when the amount came from a quote_id you supplied, so no carrier call was spent. False when this tool priced the shipment live -- either because no quote_id was given, or because the one given had expired. |
| identified_product_title | No | What the estimator understood the item to be |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag non-read-only, non-idempotent and open-world, but the description adds concrete consequences: a 30-day session record is written, two calls make two sessions, and the tool never charges because a human confirms and consents on the page. Those are exactly the behavioral facts an agent cannot infer from the annotation flags.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded summary, then side effects, then parameter rules — every section earns its place and the structure is skimmable. Minor overlap with the schema, such as repeating the 5-digit ZIP rule and the country list, slightly exceeds what the description needed to say.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given an output schema exists, the description need not explain return values, and it covers the remaining gaps: side effects, idempotency, quote precedence, expiry failure mode, and international duty handling. Nothing an agent needs to invoke this correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, yet the description still adds precedence semantics the schema does not state: quote_id overrides product, from_zip, to_zip, to_country and quantity while service still applies, and an expired quote reprices from fields or fails with missing_required_fields. It also clarifies that an unmatched service anchors the first rate rather than the cheapest, correcting a likely misreading of the schema text.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb+resource framing ("Turns a decided shipment into a payment session") and immediately names its inputs and outputs — amount plus a handoff URL to prefilled SMKlog checkout. The explicit handoff to get_parcel_quote and get_checkout_status makes it distinguishable from every sibling in the list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives positive routing (pass quote_id from get_parcel_quote; keep session_id for get_checkout_status) and explicit exclusions (no session for a non-parcel, several boxes, or an installed lithium battery crossing a border). An agent knows both when to call this and when to refuse.
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 sessionARead-onlyIdempotentInspect
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.
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | Yes | The session_id from create_checkout_link. |
Output Schema
| Name | Required | Description |
|---|---|---|
| next | No | What, if anything, the agent should do now |
| amount | No | The amount the session was anchored to, USD |
| status | Yes | Stage, in that order |
| service | No | The service the session was anchored to |
| checkout | No | The checkout the human started, null while awaiting_checkout |
| currency | No | ISO currency, USD |
| created_at | No | When create_checkout_link made the session, ISO 8601 |
| expires_at | No | When the session stops answering, ISO 8601 |
| session_id | Yes | The session asked about |
| quote_reused | No | Whether the session reused a quote_id |
TDQS
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.
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.
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.
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.
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.
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 deadlinesARead-onlyIdempotentInspect
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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
| note | Yes | What the dates are and are not |
| today | Yes | Today in New York (America/New_York), YYYY-MM-DD |
| season | Yes | Which season the dates are for |
| carriers | Yes | USPS, FedEx and UPS |
| coverage | Yes | Which lanes the dates are for |
| season_over | Yes | True after Dec 24, 2026; carriers is then empty |
TDQS
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.
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.
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.
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.
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.
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 originARead-onlyInspect
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.
| Name | Required | Description | Default |
|---|---|---|---|
| to_zip | Yes | A 5-digit ZIP for the US, else the country's postal code, e.g. M5V 2T6 (Toronto), SW1A 1AA (London). | |
| product | Yes | Plain-words item description, e.g. "65 inch flat screen TV in original box". | |
| from_zip | Yes | Origin US ZIP code, 5 digits. | |
| quantity | No | How many of the item ship together. | |
| width_in | No | Packed box width, inches. | |
| height_in | No | Packed box height, inches. | |
| length_in | No | Packed box length, inches. | |
| weight_lb | No | Packed weight, pounds. | |
| to_country | No | Two-letter destination country: US (default), CA, GB, DE, AU. | US |
Output Schema
| Name | Required | Description |
|---|---|---|
| mode | No | parcel_label_ready when rates are listed; otherwise not_a_parcel, multiple_boxes or parcel_restricted |
| rates | Yes | 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. |
| package | No | The packed box the rates were computed for |
| quote_id | No | 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. |
TDQS
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.
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.
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.
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.
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.
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 indexARead-onlyIdempotentInspect
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.
| Name | Required | Description | Default |
|---|---|---|---|
| month | No | Issue month as YYYY-MM. Omit for the newest published issue. |
Output Schema
| Name | Required | Description |
|---|---|---|
| page | No | The published issue page on smklog.com |
| cells | Yes | One entry per box and destination |
| label | No | Issue month spelled out, e.g. "August 2026" |
| month | Yes | Issue month, YYYY-MM |
| origin | No | Origin of every lane, Newark NJ (07102) |
| captured_on | Yes | The date every price in this issue was captured |
| methodology | No | How the numbers are produced |
| carrier_wins | No | How many cells each carrier priced cheapest |
| basket_average | No | Mean of the cheapest rate across all thirty cells, USD |
TDQS
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.
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.
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.
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.
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.
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 sessionARead-onlyIdempotentInspect
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.
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | Yes | The session_id from create_checkout_link. |
Output Schema
| Name | Required | Description |
|---|---|---|
| next | Yes | What, if anything, the agent should do now |
| policy | Yes | The refund policy in force |
| reason | No | |
| status | Yes | |
| currency | Yes | ISO currency, USD |
| order_id | No | SMKlog order id, the reference for support; null before checkout |
| session_id | Yes | The session asked about |
| amount_paid | Yes | USD; 0 while not_paid |
| requested_at | No | When the automatic unused-label refund was requested, ISO 8601 |
| amount_refunded | Yes | USD refunded so far |
TDQS
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.
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.
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.
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.
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.
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 rulesARead-onlyIdempotentInspect
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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
| summary | Yes | |
| batteries | Yes | The lithium battery rules, case by case |
| prohibited | Yes | Categories refused outright, with examples |
| restricted | Yes | Categories that ship only with conditions, or that the online checkout may refuse |
| policy_page | Yes | The published policy |
| descriptions | Yes | How to describe an item |
| international | Yes | Destinations and the customs declaration |
| how_smklog_checks | Yes | When SMKlog checks an item |
| restricted_handling | Yes | What a restricted item may need |
| carrier_rules_control | Yes | Who decides acceptance |
TDQS
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.
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.
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.
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.
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.
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 shipmentARead-onlyIdempotentInspect
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.
| Name | Required | Description | Default |
|---|---|---|---|
| tracking_number | Yes | Carrier tracking number from the SMKlog receipt or label page |
Output Schema
| Name | Required | Description |
|---|---|---|
| events | Yes | Scan events, newest first, up to eight |
| tracking | Yes |
TDQS
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.
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.
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.
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.
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.
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.
7 tool updates
v1.5.0- Added
calculate_billable_weight - Added
cancel_checkout_link - Changed
create_checkout_link2 fields changed- changed
Input schema / properties / quantity / descriptionPrevious value: -"Identical parcels in this shipment. Default 1."New value: +"How many of the item ship together. Default 1." - changed
Input schema / properties / service / descriptionPrevious 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."
- Added
get_holiday_shipping_deadlines - Changed
get_parcel_quote14 fields changed- changed
Input schema / properties / from_zip / descriptionPrevious value: -"Origin US ZIP code, 5 digits. The origin is always in the United States."New value: +"Origin US ZIP code, 5 digits." - changed
Input schema / properties / quantity / descriptionPrevious value: -"Identical parcels in this shipment. Default 1."New value: +"How many of the item ship together." - changed
Input schema / properties / to_zip / descriptionPrevious 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)." - changed
Input schema / properties / weight_lb / descriptionPrevious value: -"Packed weight, pounds. Decimals allowed."New value: +"Packed weight, pounds." - changed
Output schema / descriptionPrevious 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." - changed
Output schema / properties / mode / descriptionPrevious 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" - changed
Output schema / properties / quote_id / descriptionPrevious 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." - changed
Output schema / properties / rates / descriptionPrevious 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." - changed
Output schema / properties / rates / items / properties / amount / descriptionPrevious value: -"Checkout total, USD"New value: +"Checkout total, USD, SMKlog fee inside" - removed
Output schema / properties / rates / items / properties / carrier_amountRemoved value: -{ - "description": "Negotiated carrier cost, USD", - "type": "number" -} - changed
Output schema / properties / rates / items / properties / delivery_days / descriptionPrevious value: -"Business days in transit when the carrier quotes one"New value: +"Business days in transit, if quoted" - changed
Output schema / properties / rates / items / properties / delivery_estimated_date / descriptionPrevious value: -"Estimated delivery date when quoted"New value: +"Estimated delivery date, if quoted" - changed
Output schema / properties / rates / items / properties / retail_amount / descriptionPrevious value: -"Carrier retail counter price, USD; 0 when not published"New value: +"Carrier counter price, USD; 0 when not published" - removed
Output schema / properties / rates / items / properties / service_feeRemoved value: -{ - "description": "SMKlog fee, USD", - "type": "number" -}
- Added
get_refund_status - Added
get_shipping_restrictions
5 tool updates
v0.1.0- First observed
create_checkout_link - First observed
get_checkout_status - First observed
get_parcel_quote - First observed
get_price_index - First observed
track_parcel
TDQS
Scored across 10 tools
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.
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.
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.
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
Related MCP Connectors
Live USPS, UPS & FedEx shipping rates plus USPS postage and stamp prices. Free, no API key.
Multi-carrier shipping functionality with built-in, discounted carrier accounts. Compare rates, generate PDF shipping labels, schedule pickups and track packages in automated way or in your chatbox, no coding required. This is a demo server that is functional with no account needed and no auth. For production use please find our production version.
Compare rates, manage orders, buy labels, schedule pickups, and report on shipping.
Australian parcel rates from Australia Post retail and a commercial courier panel, in one call.
Related MCP Servers
- AlicenseAqualityDmaintenanceManage 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.189 npm1MIT

Easyship MCPofficial
AlicenseNot gradedqualityDmaintenanceEnables 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 npmMIT- AlicenseNot gradedqualityBmaintenanceEnables AI agents to buy US shipping labels (USPS, UPS, FedEx) with automatic cheapest-rate selection, track parcels, and refund unused labels via the EasyPost API. Stateless, bring-your-own API key, free test keys available.MIT
- AlicenseBqualityDmaintenanceCompare parcel and letter delivery prices across 60+ carriers in 27 European countries.1MIT