Skip to main content
Glama
Sign In

Zhiyong Parcel Tracking

by dev.zhiyong
OverviewDiscussionsAdmin

Track a parcel or shipment

track_parcel
Read-only

For a user-requested parcel, package, shipment, order-delivery, or waybill lookup. Required tracking_number: 5–64 letters, digits, or hyphens. If the user supplied exactly one valid number, call this tool and deliver the actual result. carrier is optional and defaults to UniUni, the only supported carrier today; additional carriers are planned but not available yet. A named unsupported carrier returns unsupported_carrier without querying UniUni. language is optional (en or zh), default en. Inspect isError and structuredContent.outcome rather than HTTP status alone. Distinguish found outcomes (delivered/in_transit), not_found, invalid, unsupported_carrier, rate_limited, carrier_error, and configuration_error. Event times are carrier-local; locations are approximate. Precise addresses, coordinates, staff, internal IDs, and raw carrier payloads are excluded. No separate lookup-authorization flag is required. Lookup inputs and filtered results are logged for up to 30 days or 1,000 records. Full MCP/A2A request sequence and result-handling workflow: https://delivery.zhiyong.dev/agent-workflow.json.

Input Schema

NameRequiredDescriptionDefault
carrierNoOptional carrier name; defaults to UniUni when omitted. UniUni is currently the only supported carrier; another named carrier is rejected without a lookup.
languageNoLanguage for event titles, details and locations. Defaults to English.en
tracking_numberYesOne user-provided parcel tracking or waybill number. This validates syntax only, not whether a parcel exists. Current carrier coverage is UniUni.

Output Schema

NameRequiredDescriptionDefault
foundYesWhether the carrier found a matching parcel.
detailNoActionable explanation for validation, carrier, configuration, or rate-limit errors.
eventsNoPrivacy-filtered scan history in carrier-local display time; street addresses and internal fields are excluded.
statusNoLocalized, normalized latest delivery status when a parcel is found.
carrierYesCarrier requested by the caller, or UniUni when omitted. Only UniUni is currently supported.
outcomeYesNormalized lookup outcome, including validation and temporary service errors.
status_codeNoCarrier status code, when available.
status_kindNoNormalized delivery state.
tracking_numberNoThe requested parcel tracking or waybill number.
estimated_deliveryNoCarrier-provided estimated delivery date, when available.
supported_carriersYesCarriers currently available through this service.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed6 schema fields changed
    • addedInput schema / properties / carrier
      Added value: +{
+  "description": "Optional carrier name; defaults to UniUni when omitted. UniUni is currently the only supported carrier; another named carrier is rejected without a lookup.",
+  "maxLength": 64,
+  "minLength": 1,
+  "type": "string"
+}
    • changedInput schema / properties / tracking_number / description
      Previous value: -"Parcel tracking or waybill number. Current carrier coverage is UniUni."New value: +"One user-provided parcel tracking or waybill number. This validates syntax only, not whether a parcel exists. Current carrier coverage is UniUni."
    • addedOutput schema / properties / carrier
      Added value: +{
+  "description": "Carrier requested by the caller, or UniUni when omitted. Only UniUni is currently supported.",
+  "type": "string"
+}
    • changedOutput schema / properties / outcome / enum
      Previous value: -[
-  "delivered",
-  "in_transit",
-  "not_found",
-  "invalid",
-  "configuration_error",
-  "carrier_error",
-  "rate_limited"
-]New value: +[
+  "delivered",
+  "in_transit",
+  "not_found",
+  "invalid",
+  "unsupported_carrier",
+  "configuration_error",
+  "carrier_error",
+  "rate_limited"
+]
    • addedOutput schema / properties / supported_carriers
      Added value: +{
+  "description": "Carriers currently available through this service.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
    • changedOutput schema / required
      Previous value: -[
-  "found",
-  "outcome"
-]New value: +[
+  "found",
+  "outcome",
+  "carrier",
+  "supported_carriers"
+]
  2. Changed3 schema fields changed
    • changedInput schema / properties / language / default
      Previous value: -"zh"New value: +"en"
    • changedInput schema / properties / language / description
      Previous value: -"Language for event titles, details and locations."New value: +"Language for event titles, details and locations. Defaults to English."
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "additionalProperties": false,
+  "properties": {
+    "detail": {
+      "description": "Actionable explanation for validation, carrier, configuration, or rate-limit errors.",
+      "type": "string"
+    },
+    "estimated_delivery": {
+      "description": "Carrier-provided estimated delivery date, when available.",
+      "type": "string"
+    },
+    "events": {
+      "description": "Privacy-filtered scan history in carrier-local display time; street addresses and internal fields are excluded.",
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "detail": {
+            "description": "Safe, normalized event explanation, when available.",
+            "type": "string"
+          },
+          "location": {
+            "description": "Approximate city or region, when available.",
+            "type": "string"
+          },
+          "status": {
+            "description": "Localized, normalized event title.",
+            "type": "string"
+          },
+          "time": {
+            "description": "Event time as displayed by the carrier, without UTC conversion.",
+            "type": "string"
+          },
+          "time_basis": {
+            "enum": [
+              "carrier_local"
+            ],
+            "type": "string"
+          }
+        },
+        "required": [
+          "time",
+          "time_basis",
+          "status"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "found": {
+      "description": "Whether the carrier found a matching parcel.",
+      "type": "boolean"
+    },
+    "outcome": {
+      "description": "Normalized lookup outcome, including validation and temporary service errors.",
+      "enum": [
+        "delivered",
+        "in_transit",
+        "not_found",
+        "invalid",
+        "configuration_error",
+        "carrier_error",
+        "rate_limited"
+      ],
+      "type": "string"
+    },
+    "status": {
+      "description": "Localized, normalized latest delivery status when a parcel is found.",
+      "type": "string"
+    },
+    "status_code": {
+      "description": "Carrier status code, when available.",
+      "type": "string"
+    },
+    "status_kind": {
+      "description": "Normalized delivery state.",
+      "enum": [
+        "delivered",
+        "in_transit",
+        "exception"
+      ],
+      "type": "string"
+    },
+    "tracking_number": {
+      "description": "The requested parcel tracking or waybill number.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "found",
+    "outcome"
+  ],
+  "type": "object"
+}
  3. Changed1 schema field changed
    • changedInput schema / properties / tracking_number / description
      Previous value: -"A UniUni parcel tracking / waybill number (UniUni 运单号)."New value: +"Parcel tracking or waybill number. Current carrier coverage is UniUni."
  4. Changed2 schema fields changed
    • changedInput schema / properties / language / description
      Previous value: -"Language for status labels."New value: +"Language for event titles, details and locations."
    • changedInput schema / properties / tracking_number / description
      Previous value: -"The UniUni tracking / waybill number."New value: +"A UniUni parcel tracking / waybill number (UniUni 运单号)."
  5. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Annotations cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), and the description goes well beyond them: it enumerates the full outcome taxonomy, states that times are carrier-local and locations approximate, lists what is deliberately excluded from results, notes that no separate lookup-authorization flag is required, and discloses a 30-day/1,000-record logging retention window. The idempotentHint=false annotation is consistent with a live tracking lookup whose underlying state changes, so there is no contradiction.

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?

It is long but front-loaded: the purpose and the required tracking_number constraint come first, followed by parameter defaults, then error handling, then data-handling caveats. Most sentences earn their place, though the outcome taxonomy and exclusions list make it denser than strictly necessary for a three-parameter read tool.

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, so return-value shape need not be explained, yet the description still tells the agent how to interpret results (isError, structuredContent.outcome, found vs not_found vs rate_limited vs configuration_error). Combined with carrier defaults, privacy exclusions, logging retention, and a link to the full workflow document, nothing an agent needs to call or interpret this tool is missing.

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

Parameters3/5

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

Schema description coverage is 100%, so all three parameters (including the enum and defaults) are already documented in the schema itself. The description largely restates the 5-64 character constraint and the UniUni default; its only additive note is the carrier roadmap ('additional carriers are planned but not available yet'), which is marginal. Baseline 3 is appropriate when the schema carries the parameter burden.

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 states a specific verb-plus-resource scope and enumerates the user-facing synonyms it covers (parcel, package, shipment, order-delivery, waybill), so an agent immediately knows what request class routes here. There are no sibling tools to disambiguate against, and the title reinforces the same meaning without adding noise.

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 gives an explicit trigger condition ('If the user supplied exactly one valid number, call this tool and deliver the actual result') and an explicit boundary for the carrier parameter (defaults to UniUni, named unsupported carriers are rejected without querying). The guidance on inspecting isError and structuredContent.outcome rather than HTTP status is actionable operating instruction rather than vague context.

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

All Zhiyong Parcel Tracking toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources