SMKlog Parcel Shipping Rates

Refund status of a checkout session

get_refund_status

Read-onlyIdempotent

Check whether the payment behind a checkout session was refunded, including status, amount, and reason; this read-only lookup never starts a refund.

Instructions

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.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "session_id": "<session_id>"
    },
    "name": "get_refund_status"
  }
}

Input Schema

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

Schema Changelog

Changes observed during successful MCP inspections.

Addedv1.5.0Nov 8, 2026

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.

Deploy Server