Skip to main content
Glama

Search by Tracking Number

search_tracking_by_number
Read-only

Returns existing tracking results for a raw tracking number across trackers already on the account, without needing a trackerId. Free read: never creates a tracker and never triggers a new crawl. Responds 404 tracker_not_found if no tracker exists for that number — in that case use search_tracking (per-call) or track (per-shipment). Use this first when a tracker may already exist.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
trackingNumberYesThe raw shipment tracking number to search for (e.g. 1Z999AA10123456784).

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
trackingsYesOne entry per matched tracker or shipment.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "$schema": "http://json-schema.org/draft-07/schema#",
      +  "additionalProperties": {},
      +  "properties": {
      +    "trackings": {
      +      "anyOf": [
      +        {
      +          "items": {
      +            "additionalProperties": {},
      +            "properties": {
      +              "events": {
      +                "anyOf": [
      +                  {
      +                    "items": {
      +                      "additionalProperties": {},
      +                      "properties": {
      +                        "courierCode": {
      +                          "anyOf": [
      +                            {
      +                              "type": "string"
      +                            },
      +                            {
      +                              "type": "null"
      +                            }
      +                          ],
      +                          "description": "Courier code linked to this event; refers to the get_couriers list."
      +                        },
      +                        "datetime": {
      +                          "anyOf": [
      +                            {
      +                              "type": "string"
      +                            },
      +                            {
      +                              "type": "null"
      +                            }
      +                          ],
      +                          "description": "DEPRECATED — use occurrenceDatetime."
      +                        },
      +                        "eventId": {
      +                          "anyOf": [
      +                            {
      +                              "type": "string"
      +                            },
      +                            {
      +                              "type": "null"
      +                            }
      +                          ],
      +                          "description": "Unique identifier of this event in Ship24."
      +                        },
      +                        "eventTrackingNumber": {
      +                          "anyOf": [
      +                            {
      +                              "type": "string"
      +                            },
      +                            {
      +                              "type": "null"
      +                            }
      +                          ],
      +                          "description": "The tracking number the event was actually found on."
      +                        },
      +                        "hasNoTime": {
      +                          "anyOf": [
      +                            {
      +                              "type": "boolean"
      +                            },
      +                            {
      +                              "type": "null"
      +                            }
      +                          ],
      +                          "description": "DEPRECATED — true when the courier reported a date with no time."
      +                        },
      +                        "location": {
      +                          "anyOf": [
      +                            {
      +                              "type": "string"
      +                            },
      +                            {
      +                              "type": "null"
      +                            }
      +                          ],
      +                          "description": "Raw location text as reported by the courier."
      +                        },
      +                        "occurrenceDatetime": {
      +                          "anyOf": [
      +                            {
      +                              "type": "string"
      +                            },
      +                            {
      +                              "type": "null"
      +                            }
      +                          ],
      +                          "description": "When the event occurred."
      +                        },
      +                        "order": {
      +                          "anyOf": [
      +                            {
      +                              "type": "number"
      +                            },
      +                            {
      +                              "type": "null"
      +                            }
      +                          ],
      +                          "description": "Tie-breaker when several events share the same occurrenceDatetime; lower comes first."
      +                        },
      +                        "sourceCode": {
      +                          "anyOf": [
      +                            {
      +                              "type": "string"
      +                            },
      +                            {
      +                              "type": "null"
      +                            }
      +                          ],
      +                          "description": "Internal code of the source this event came from. These codes may change at any time."
      +                        },
      +                        "status": {
      +                          "anyOf": [
      +                            {
      +                              "type": "string"
      +                            },
      +                            {
      +                              "type": "null"
      +                            }
      +                          ],
      +                          "description": "Raw status text as reported by the courier."
      +                        },
      +                        "statusCategory": {
      +                          "anyOf": [
      +                            {
      +                              "type": "string"
      +                            },
      +                            {
      +                              "type": "null"
      +                            }
      +                          ],
      +                          "description": "Ship24 status category for the event."
      +                        },
      +                        "statusCode": {
      +                          "anyOf": [
      +                            {
      +                              "type": "string"
      +                            },
      +                            {
      +                              "type": "null"
      +                            }
      +                          ],
      +                          "description": "Ship24 normalised status code for the event."
      +                        },
      +                        "statusMilestone": {
      +                          "anyOf": [
      +                            {
      +                              "type": "string"
      +                            },
      +                            {
      +                              "type": "null"
      +                            }
      +                          ],
      +                          "description": "Milestone at the time of the event: pending | info_received | in_transit | out_for_delivery | failed_attempt | available_for_pickup | delivered | exception."
      +                        },
      +                        "trackingNumber": {
      +                          "anyOf": [
      +                            {
      +                              "type": "string"
      +                            },
      +                            {
      +                              "type": "null"
      +                            }
      +                          ],
      +                          "description": "The original tracking number used to create the tracker."
      +                        },
      +                        "utcOffset": {
      +                          "anyOf": [
      +                            {
      +                              "type": "string"
      +                            },
      +                            {
      +                              "type": "null"
      +                            }
      +                          ],
      +                          "description": "DEPRECATED — the offset is already carried by occurrenceDatetime."
      +                        }
      +                      },
      +                      "type": "object"
      +                    },
      +                    "type": "array"
      +                  },
      +                  {
      +                    "type": "null"
      +                  }
      +                ],
      +                "description": "Tracking events, most recent first."
      +              },
      +              "shipment": {
      +                "anyOf": [
      +                  {
      +                    "additionalProperties": {},
      +                    "properties": {
      +                      "delivery": {
      +                        "anyOf": [
      +                          {
      +                            "additionalProperties": {},
      +                            "properties": {
      +                              "aiPredictiveDeliveryDate": {
      +                                "anyOf": [
      +                                  {
      +                                    "additionalProperties": {},
      +                                    "properties": {
      +                                      "from": {
      +                                        "anyOf": [
      +                                          {
      +                                            "type": "string"
      +                                          },
      +                                          {
      +                                            "type": "null"
      +                                          }
      +                                        ],
      +                                        "description": "Earliest date of the window."
      +                                      },
      +                                      "to": {
      +                                        "anyOf": [
      +                                          {
      +                                            "type": "string"
      +                                          },
      +                                          {
      +                                            "type": "null"
      +                                          }
      +                                        ],
      +                                        "description": "Latest date of the window."
      +                                      }
      +                                    },
      +                                    "type": "object"
      +                                  },
      +                                  {
      +                                    "type": "null"
      +                                  }
      +                                ],
      +                                "description": "Ship24 AI-predicted window. Omitted entirely unless enabled on the account."
      +                              },
      +                              "courierEstimatedDeliveryDate": {
      +                                "anyOf": [
      +                                  {
      +                                    "additionalProperties": {},
      +                                    "properties": {
      +                                      "from": {
      +                                        "anyOf": [
      +                                          {
      +                                            "type": "string"
      +                                          },
      +                                          {
      +                                            "type": "null"
      +                                          }
      +                                        ],
      +                                        "description": "Earliest date of the window."
      +                                      },
      +                                      "to": {
      +                                        "anyOf": [
      +                                          {
      +                                            "type": "string"
      +                                          },
      +                                          {
      +                                            "type": "null"
      +                                          }
      +                                        ],
      +                                        "description": "Latest date of the window."
      +                                      }
      +                                    },
      +                                    "type": "object"
      +                                  },
      +                                  {
      +                                    "type": "null"
      +                                  }
      +                                ],
      +                                "description": "Window promised by the courier."
      +                              },
      +                              "estimatedDeliveryDate": {
      +                                "anyOf": [
      +                                  {
      +                                    "type": "string"
      +                                  },
      +                                  {
      +                                    "type": "null"
      +                                  }
      +                                ],
      +                                "description": "Estimated delivery date, when the courier provides one."
      +                              },
      +                              "service": {
      +                                "anyOf": [
      +                                  {
      +                                    "type": "string"
      +                                  },
      +                                  {
      +                                    "type": "null"
      +                                  }
      +                                ],
      +                                "description": "Name of the logistics service or product used."
      +                              },
      +                              "signedBy": {
      +                                "anyOf": [
      +                                  {
      +                                    "type": "string"
      +                                  },
      +                                  {
      +                                    "type": "null"
      +                                  }
      +                                ],
      +                                "description": "DEPRECATED — always null."
      +                              }
      +                            },
      +                            "type": "object"
      +                          },
      +                          {
      +                            "type": "null"
      +                          }
      +                        ],
      +                        "description": "Delivery dates and service level."
      +                      },
      +                      "destinationCountryCode": {
      +                        "anyOf": [
      +                          {
      +                            "type": "string"
      +                          },
      +                          {
      +                            "type": "null"
      +                          }
      +                        ],
      +                        "description": "Detected destination country (ISO alpha-2)."
      +                      },
      +                      "originCountryCode": {
      +                        "anyOf": [
      +                          {
      +                            "type": "string"
      +                          },
      +                          {
      +                            "type": "null"
      +                          }
      +                        ],
      +                        "description": "Detected origin country (ISO alpha-2)."
      +                      },
      +                      "recipient": {
      +                        "anyOf": [
      +                          {
      +                            "additionalProperties": {},
      +                            "properties": {
      +                              "address": {
      +                                "anyOf": [
      +                                  {
      +                                    "type": "string"
      +                                  },
      +                                  {
      +                                    "type": "null"
      +                                  }
      +                                ],
      +                                "description": "Recipient address."
      +                              },
      +                              "city": {
      +                                "anyOf": [
      +                                  {
      +                                    "type": "string"
      +                                  },
      +                                  {
      +                                    "type": "null"
      +                                  }
      +                                ],
      +                                "description": "Recipient city."
      +                              },
      +                              "name": {
      +                                "anyOf": [
      +                                  {
      +                                    "type": "string"
      +                                  },
      +                                  {
      +                                    "type": "null"
      +                                  }
      +                                ],
      +                                "description": "Recipient name."
      +                              },
      +                              "postCode": {
      +                                "anyOf": [
      +                                  {
      +                                    "type": "string"
      +                                  },
      +                                  {
      +                                    "type": "null"
      +                                  }
      +                                ],
      +                                "description": "Recipient postal code."
      +                              },
      +                              "subdivision": {
      +                                "anyOf": [
      +                                  {
      +                                    "type": "string"
      +                                  },
      +                                  {
      +                                    "type": "null"
      +                                  }
      +                                ],
      +                                "description": "Recipient state or province."
      +                              }
      +                            },
      +                            "type": "object"
      +                          },
      +                          {
      +                            "type": "null"
      +                          }
      +                        ],
      +                        "description": "Recipient details. All fields are nulled unless the account may receive personal data."
      +                      },
      +                      "shipmentId": {
      +                        "anyOf": [
      +                          {
      +                            "type": "string"
      +                          },
      +                          {
      +                            "type": "null"
      +                          }
      +                        ],
      +                        "description": "Unique identifier of the parcel in Ship24."
      +                      },
      +                      "statusCategory": {
      +                        "anyOf": [
      +                          {
      +                            "type": "string"
      +                          },
      +                          {
      +                            "type": "null"
      +                          }
      +                        ],
      +                        "description": "Ship24 status category for the shipment."
      +                      },
      +                      "statusCode": {
      +                        "anyOf": [
      +                          {
      +                            "type": "string"
      +                          },
      +                          {
      +                            "type": "null"
      +                          }
      +                        ],
      +                        "description": "Ship24 normalised status code for the shipment."
      +                      },
      +                      "statusMilestone": {
      +                        "anyOf": [
      +                          {
      +                            "type": "string"
      +                          },
      +                          {
      +                            "type": "null"
      +                          }
      +                        ],
      +                        "description": "Current milestone; same value set as event.statusMilestone."
      +                      },
      +                      "trackingNumbers": {
      +                        "anyOf": [
      +                          {
      +                            "items": {
      +                              "additionalProperties": {},
      +                              "properties": {
      +                                "tn": {
      +                                  "anyOf": [
      +                                    {
      +                                      "type": "string"
      +                                    },
      +                                    {
      +                                      "type": "null"
      +                                    }
      +                                  ],
      +                                  "description": "A tracking number linked to the shipment."
      +                                }
      +                              },
      +                              "type": "object"
      +                            },
      +                            "type": "array"
      +                          },
      +                          {
      +                            "type": "null"
      +                          }
      +                        ],
      +                        "description": "All tracking numbers linked to the shipment."
      +                      }
      +                    },
      +                    "type": "object"
      +                  },
      +                  {
      +                    "type": "null"
      +                  }
      +                ],
      +                "description": "General shipment information and current status."
      +              },
      +              "statistics": {
      +                "anyOf": [
      +                  {
      +                    "additionalProperties": {},
      +                    "properties": {
      +                      "timestamps": {
      +                        "anyOf": [
      +                          {
      +                            "additionalProperties": {},
      +                            "properties": {
      +                              "availableForPickupDatetime": {
      +                                "anyOf": [
      +                                  {
      +                                    "type": "string"
      +                                  },
      +                                  {
      +                                    "type": "null"
      +                                  }
      +                                ],
      +                                "description": "First occurrence of the available_for_pickup milestone."
      +                              },
      +                              "deliveredDatetime": {
      +                                "anyOf": [
      +                                  {
      +                                    "type": "string"
      +                                  },
      +                                  {
      +                                    "type": "null"
      +                                  }
      +                                ],
      +                                "description": "First occurrence of the delivered milestone."
      +                              },
      +                              "exceptionDatetime": {
      +                                "anyOf": [
      +                                  {
      +                                    "type": "string"
      +                                  },
      +                                  {
      +                                    "type": "null"
      +                                  }
      +                                ],
      +                                "description": "First occurrence of the exception milestone."
      +                              },
      +                              "failedAttemptDatetime": {
      +                                "anyOf": [
      +                                  {
      +                                    "type": "string"
      +                                  },
      +                                  {
      +                                    "type": "null"
      +                                  }
      +                                ],
      +                                "description": "First occurrence of the failed_attempt milestone."
      +                              },
      +                              "inTransitDatetime": {
      +                                "anyOf": [
      +                                  {
      +                                    "type": "string"
      +                                  },
      +                                  {
      +                                    "type": "null"
      +                                  }
      +                                ],
      +                                "description": "First occurrence of the in_transit milestone."
      +                              },
      +                              "infoReceivedDatetime": {
      +                                "anyOf": [
      +                                  {
      +                                    "type": "string"
      +                                  },
      +                                  {
      +                                    "type": "null"
      +                                  }
      +                                ],
      +                                "description": "First occurrence of the info_received milestone."
      +                              },
      +                              "outForDeliveryDatetime": {
      +                                "anyOf": [
      +                                  {
      +                                    "type": "string"
      +                                  },
      +                                  {
      +                                    "type": "null"
      +                                  }
      +                                ],
      +                                "description": "First occurrence of the out_for_delivery milestone."
      +                              }
      +                            },
      +                            "type": "object"
      +                          },
      +                          {
      +                            "type": "null"
      +                          }
      +                        ],
      +                        "description": "When each milestone was first reached; null for milestones never reached."
      +                      }
      +                    },
      +                    "type": "object"
      +                  },
      +                  {
      +                    "type": "null"
      +                  }
      +                ],
      +                "description": "Milestone timestamps for the shipment lifecycle."
      +              },
      +              "tracker": {
      +                "anyOf": [
      +                  {
      +                    "additionalProperties": {},
      +                    "properties": {
      +                      "clientTrackerId": {
      +                        "anyOf": [
      +                          {
      +                            "type": "string"
      +                          },
      +                          {
      +                            "type": "null"
      +                          }
      +                        ],
      +                        "description": "Your own tracker identifier, usable with searchBy=clientTrackerId."
      +                      },
      +                      "courierCode": {
      +                        "anyOf": [
      +                          {
      +                            "anyOf": [
      +                              {
      +                                "items": {
      +                                  "type": "string"
      +                                },
      +                                "type": "array"
      +                              },
      +                              {
      +                                "type": "string"
      +                              }
      +                            ]
      +                          },
      +                          {
      +                            "type": "null"
      +                          }
      +                        ],
      +                        "description": "Courier code(s) pinned on this tracker."
      +                      },
      +                      "createdAt": {
      +                        "anyOf": [
      +                          {
      +                            "type": "string"
      +                          },
      +                          {
      +                            "type": "null"
      +                          }
      +                        ],
      +                        "description": "When the tracker was created."
      +                      },
      +                      "isSubscribed": {
      +                        "anyOf": [
      +                          {
      +                            "type": "boolean"
      +                          },
      +                          {
      +                            "type": "null"
      +                          }
      +                        ],
      +                        "description": "False means the tracker is archived and no longer used for tracking."
      +                      },
      +                      "isTracked": {
      +                        "anyOf": [
      +                          {
      +                            "type": "boolean"
      +                          },
      +                          {
      +                            "type": "null"
      +                          }
      +                        ],
      +                        "description": "False means tracking stopped (delivered, inactive or unsubscribed); existing results remain."
      +                      },
      +                      "shipmentReference": {
      +                        "anyOf": [
      +                          {
      +                            "type": "string"
      +                          },
      +                          {
      +                            "type": "null"
      +                          }
      +                        ],
      +                        "description": "Your own shipment reference, as supplied at creation."
      +                      },
      +                      "trackerId": {
      +                        "anyOf": [
      +                          {
      +                            "type": "string"
      +                          },
      +                          {
      +                            "type": "null"
      +                          }
      +                        ],
      +                        "description": "Ship24 tracker identifier; pass this to get_tracking_results."
      +                      },
      +                      "trackingNumber": {
      +                        "anyOf": [
      +                          {
      +                            "type": "string"
      +                          },
      +                          {
      +                            "type": "null"
      +                          }
      +                        ],
      +                        "description": "Tracking number this tracker follows."
      +                      }
      +                    },
      +                    "type": "object"
      +                  },
      +                  {
      +                    "type": "null"
      +                  }
      +                ],
      +                "description": "The tracker this result comes from. Absent for search_tracking, which creates no tracker."
      +              }
      +            },
      +            "type": "object"
      +          },
      +          "type": "array"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ],
      +      "description": "One entry per matched tracker or shipment."
      +    }
      +  },
      +  "required": [
      +    "trackings"
      +  ],
      +  "type": "object"
      +}
  2. First observed

TDQS

A4.7/5.0
Behavior5/5

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

Annotations already declare readOnlyHint=true and openWorldHint=false, but the description goes further by explaining the concrete side-effect-free guarantees: 'never creates a tracker and never triggers a new crawl.' It also discloses the 404 tracker_not_found behavior, which is important for agents handling missing-tracker cases. This is exactly the kind of behavioral context the dimension rewards.

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 three sentences with no filler. The first sentence states the core function and key differentiator, the second covers safety guarantees, and the third handles error behavior and alternatives. Every sentence earns its place, and the most decision-relevant content is front-loaded.

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-only tool with an output schema and safety annotations, the description is complete. It covers the operation, queried resource scope, side effects, error response, and routing to alternatives. There is nothing an agent needs to call this tool correctly that is missing, and the presence of an output schema means return-value details need not be repeated.

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?

The schema already fully documents the single parameter with a type, minLength, and an example. The description adds the framing 'raw tracking number' and 'across trackers already on the account,' which slightly enriches the parameter's meaning, but it does not add substantially new information beyond the schema. With 100% schema coverage, the baseline of 3 is appropriate.

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 verb and resource: 'Returns existing tracking results for a raw tracking number across trackers already on the account.' It also clarifies the key distinction that no trackerId is needed, and it distinguishes itself from siblings by naming search_tracking and track as alternatives. This gives an agent a clear, unambiguous understanding of what the tool does.

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 provides explicit when-to-use guidance: 'Use this first when a tracker may already exist.' It also gives a concrete fallback path on 404, directing the agent to search_tracking or track with selection criteria ('per-call' vs 'per-shipment'). This fully resolves the choice among the closely related sibling tools.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources