Track parcels across 2,500+ carriers and 3PLs: live delivery status, event history, carrier lookup.
Creates up to 100 trackers in one request. Each tracker object accepts the same fields as create_tracker — see that tool for field details. Not fully idempotent: retrying a failed bulk request may partially create trackers. Returns counts of created, ignored (duplicate), and failed trackers plus per-item details.
| Name | Required | Description | Default |
|---|---|---|---|
| trackers | Yes | Array of tracker objects to create (minimum 1, maximum 100). |
| Name | Required | Description |
|---|---|---|
| data | No | Per-item outcome, in submission order. Null when status is error. |
| error | No | Request-level error. Null unless the whole request failed. |
| status | No | success (all created or already existing) | partial (successes and errors) | error (all failed, or a request-level error). |
| summary | No | Per-request counts. Null when status is error. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the annotations by explicitly warning that the operation is not fully idempotent and that retries may partially create trackers. It also discloses the return shape—counts of created, ignored/duplicate, and failed trackers plus per-item details—which is valuable behavioral context that annotations alone do not provide.
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?
Three sentences carry exactly the necessary information: the batch capability, the relationship to create_tracker, and critical idempotency/return behavior. Every sentence earns its place, and the most important limit is front-loaded.
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 the rich input schema and the existence of an output schema, the description covers the key operational caveat (partial creation on retry), the size limit, duplicate handling, and the return summary. Nothing essential for calling this tool 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%, so the schema already documents the 'trackers' array and its item fields. The description adds a helpful cross-reference to create_tracker for field details but does not enrich parameter meaning beyond the schema, so the baseline of 3 is appropriate.
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: 'Creates up to 100 trackers in one request.' It clearly differentiates this from the sibling create_tracker by emphasizing the batch nature and the 100-item limit, so an agent can tell it apart immediately.
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 'in one request' and 'up to 100' language clearly positions this tool for batch creation, and the reference to create_tracker for field details gives context about its relationship to the single-create tool. It does not explicitly state 'use create_tracker for a single tracker and this for multiple trackers,' but the use case is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Creates a new tracker for a tracking number. Use when the user explicitly wants ongoing monitoring or webhook updates; results arrive asynchronously — for immediate results use track or search_tracking. Idempotent: same parameters reuse the existing tracker; any field change creates a new one. Subscribes to webhook updates if configured. Returns the created tracker including its Ship24 trackerId.
| Name | Required | Description | Default |
|---|---|---|---|
| settings | No | ||
| courierCode | No | Courier codes for this tracker (max 3). Use get_couriers for valid codes. IMPORTANT: Check each courier's requiredFields array — any listed fields should be provided, otherwise the courier may not return any tracking data. | |
| courierName | No | Courier name (informational). | |
| orderNumber | No | Associated order number. | |
| trackingUrl | No | Courier tracking URL. | |
| shippingDate | No | Date the package was shipped (YYYY-MM-DD or ISO 8601). | |
| trackingNumber | Yes | Tracking number to monitor. | |
| clientTrackerId | No | Your unique identifier for this tracker, for lookup via searchBy=clientTrackerId. | |
| originCountryCode | No | Origin country code (ISO alpha-2, e.g. US). | |
| shipmentReference | No | Internal reference for the shipment. | |
| destinationPostCode | No | Destination postal/ZIP code. | |
| destinationCountryCode | No | Destination country code (ISO alpha-2). |
| Name | Required | Description |
|---|---|---|
| tracker | Yes | The tracker. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes beyond the idempotentHint annotation by explaining exactly what idempotency means here: same parameters reuse the existing tracker, while any field change creates a new one. Also discloses asynchronous webhook subscription behavior and specifies that the created tracker's Ship24 trackerId is returned in the response.
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?
Four sentences deliver the full behavioral contract without redundancy: creation purpose, usage timing, async behavior, idempotency, webhooks, and return value. The critical info is front-loaded and every clause earns its place.
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 the output schema and rich annotations, the description covers all essential decision factors: when to use, what happens after creation, idempotency behavior, and what the response contains. No critical gap remains for an agent selecting and invoking this tool correctly.
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?
The input schema already provides 92% parameter coverage, so the description need not restate field meanings. The description adds context about parameter reuse via idempotency but no parameter-specific semantics beyond the schema, which meets the baseline for high schema coverage.
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 ('Creates a new tracker') and explicitly distinguishes ongoing monitoring from immediate result tools ('for immediate results use track or search_tracking'). The description makes the tool's purpose unmistakable and separates it from its siblings.
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 an explicit condition for use ('when the user explicitly wants ongoing monitoring or webhook updates') and names specific alternatives for the opposite case ('track or search_tracking'). Also explains the asynchronous nature of results, which is critical for proper tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves the full webhook push history for a tracker. Returns metadata (trackingNumber, trackerId, clientTrackerId, webhookUrl, lastSuccessfulPushAt, lastFailedPushAt) and a list of all sent or failed pushes with status, pushTimestamp, requestBody, responseBody, responseHeaders, and responseStatusCode. Pending (unsent) webhooks are excluded. Results are sorted newest first. Rate-limited to 1 request/second per tracker.
| Name | Required | Description | Default |
|---|---|---|---|
| searchBy | No | How to interpret trackerId: default is Ship24 trackerId, use "clientTrackerId" for your own reference. | |
| trackerId | Yes | Ship24 trackerId, or clientTrackerId when searchBy="clientTrackerId". |
| Name | Required | Description |
|---|---|---|
| metadata | No | Tracker and webhook endpoint context. |
| webhooks | Yes | Sent and failed pushes, newest first. Pending webhooks are excluded. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint already provided, the description adds valuable behavioral details: pending webhooks are excluded, results are sorted newest first, and the operation is rate-limited to 1 request/second per tracker. These details go beyond the annotations and help the agent set correct expectations.
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 compact and front-loaded, stating the core purpose first, then adding return fields and behavioral caveats. Every sentence provides useful information without redundancy.
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?
The description covers what is returned, what is excluded, ordering behavior, and rate limits, while the output schema handles return structure. For a two-parameter read-only tool, this is complete enough for an agent to select and invoke it correctly.
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?
The schema already describes both parameters fully, including searchBy's enum and the meaning of trackerId. The description does not add additional parameter-level detail, but none is needed given the 100% schema coverage.
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: 'Retrieves the full webhook push history for a tracker.' It clearly differentiates itself from siblings like get_tracker and resend_webhooks by focusing on webhook push history rather than tracking results or resending webhooks.
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 makes clear this tool is for retrieving webhook push history, which strongly implies when to use it. It does not explicitly name alternatives or state when not to use it, but the context is sufficient to guide an agent toward this tool for webhook history needs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the list of all couriers supported by Ship24, including their unique courier codes, human-readable names, and any special tracking requirements. Use this tool to discover valid courierCode values before creating or updating trackers, or to help identify which courier handles a particular tracking number format. Note: this endpoint has a rate limit of 1 request/second; cache results when possible.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| couriers | Yes | All couriers supported by Ship24. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description adds meaningful behavioral context: the endpoint has a 1 request/second rate limit and results should be cached. It also tells the agent what data is included, which helps set expectations for the response.
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?
Three sentences with no wasted words: the return value is stated first, then use cases, then a critical rate-limit warning. Every sentence adds value and the most important operational detail is clearly flagged.
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 zero-parameter read-only tool with an output schema already present, the description is complete. It covers what the tool returns, when to use it, and an important rate-limit constraint. Nothing essential 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?
The tool has zero parameters, so there is no parameter documentation burden on the description. The baseline for a zero-parameter tool is 4, and the description appropriately focuses on output and usage rather than parameters.
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 clearly states the tool returns the list of all supported couriers with courier codes, human-readable names, and special tracking requirements. This is a specific verb-plus-resource statement that is easily distinguished from sibling tools like create_tracker or get_tracking_results.
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 provides clear context for when to use the tool: before creating or updating trackers to discover valid courierCode values, and to identify which courier handles a tracking number format. It does not explicitly name alternatives or exclusion conditions, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves a single tracker by trackerId (or clientTrackerId when searchBy is set). Returns tracker metadata only — use get_tracking_results for events and status.
| Name | Required | Description | Default |
|---|---|---|---|
| searchBy | No | How to interpret trackerId: default is Ship24 trackerId, use "clientTrackerId" for your own reference. | |
| trackerId | Yes | Ship24 trackerId, or clientTrackerId when searchBy="clientTrackerId". |
| Name | Required | Description |
|---|---|---|
| tracker | Yes | The tracker. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description adds the important behavioral boundary that only tracker metadata is returned, not events or status. This goes beyond the schema by setting expectations about response scope, though it does not discuss error behavior or lookup failure handling.
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?
Two sentences, no filler. The core operation and key distinction from get_tracking_results are front-loaded, and every clause adds value.
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 simple single-resource read with a full output schema, read-only annotations, and a clear sibling pointer, the description is complete. An agent can correctly invoke the tool and understand what it will get back without needing additional 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 description coverage is 100%, and both parameters are well documented with descriptions and an enum. The tool description adds little beyond the schema, only restating that searchBy alters interpretation of trackerId. Per the baseline, this is adequate but not enhanced.
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 uses a specific verb ('Retrieves') and resource ('a single tracker'), and distinguishes this from get_tracking_results by stating it returns metadata only. It also clearly differentiates from list_trackers by focusing on a single tracker rather than a 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?
The description explicitly instructs the agent to use get_tracking_results for events and status, which is a direct when-to-use/alternative statement. It also clarifies the dual lookup modes via trackerId and clientTrackerId, giving clear context for selecting this tool over siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns full tracking results for an existing tracker: metadata, shipment status, all events in order, and delivery statistics. Primary tool for "where is my package?" when you have a trackerId. statusMilestone values: pending | info_received | in_transit | out_for_delivery | failed_attempt | available_for_pickup | delivered | exception.
| Name | Required | Description | Default |
|---|---|---|---|
| searchBy | No | How to interpret trackerId: default is Ship24 trackerId, use "clientTrackerId" for your own reference. | |
| trackerId | Yes | Ship24 trackerId, or clientTrackerId when searchBy="clientTrackerId". |
| Name | Required | Description |
|---|---|---|
| trackings | Yes | One entry per matched tracker or shipment. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=true and openWorldHint=false; the description goes further by specifying that events are returned in order and listing the allowed statusMilestone values. It does not discuss pagination or errors, but for a read-only lookup with an output schema this is adequate added behavioral 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?
Three short sentences each earn their place: the return payload, the primary use case, and the statusMilestone enum. It is front-loaded with the core behavior and contains no filler.
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?
The tool is a simple read-only getter with one required parameter, a fully described input schema, and an output schema. The description covers what it returns, in what order, and when to use it, so an agent has enough to invoke it correctly.
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?
Input schema description coverage is 100%, so the schema already documents trackerId and searchBy meanings. The description mentions needing a trackerId and alludes to status values, but adds no parameter-level detail beyond the schema, giving the baseline score.
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?
Description states a specific verb ('Returns') and resource ('full tracking results for an existing tracker') and enumerates the content: metadata, shipment status, events in order, and delivery statistics. It also marks itself as the primary tool for 'where is my package?' when a trackerId is available, distinguishing it from search-oriented siblings.
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 explicitly says when to use this tool: when you have a trackerId and need package status context. It does not explicitly name sibling tools as alternatives or state when not to use it, but the 'primary tool for...' framing gives clear usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns a paginated list of all trackers. Supports offset (page/limit) or cursor-based pagination. Filter by subscription status with isSubscribed.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (1-indexed). | |
| sort | No | Sort order by createdAt. 1 = ascending (oldest first, default), -1 = descending (newest first). | |
| limit | No | Results per page (max 500). |
| Name | Required | Description |
|---|---|---|
| trackers | Yes | Trackers on the requested page. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description adds pagination/filtering behavior. However, it claims cursor-based pagination and an isSubscribed parameter that are not present in the input schema, making the behavioral guidance misleading and unreliable.
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 compact and front-loads the core action in the first sentence. The second sentence is short but contains inaccuracies, so it does not fully earn its place; still, the overall structure is efficient.
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?
The output schema and annotations cover some context, but the mismatch between the described pagination/filter options and the actual schema leaves an agent without a valid way to invoke the promised cursor or isSubscribed behavior. The description is therefore not complete enough for reliable tool selection and invocation.
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 introduces 'isSubscribed' and 'cursor' as though they were parameters while the schema only defines page, sort, and limit. It adds no clarifying semantics for sort and creates confusion about available arguments.
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 verb and resource: 'Returns a paginated list of all trackers.' This clearly distinguishes it from single-item tools like get_tracker and search-focused siblings.
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 gives clear context for when to use the tool: to list all trackers, with pagination and subscription-status filtering. It does not explicitly name alternatives or exclusions, but the purpose is clear enough that an agent can infer the basic use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replays all webhook events for a tracker. Use when your endpoint missed or failed to process previous notifications. Terminates any in-flight webhook delivery for this tracker and invalidates its existing webhook payload records before regenerating and resending them — do not call repeatedly in quick succession. Rate-limited to 1 request/second per tracker.
| Name | Required | Description | Default |
|---|---|---|---|
| searchBy | No | How to interpret trackerId: default is Ship24 trackerId, use "clientTrackerId" for your own reference. | |
| trackerId | Yes | Ship24 trackerId, or clientTrackerId when searchBy="clientTrackerId". |
| Name | Required | Description |
|---|---|---|
| summary | Yes | Outcome of the webhook replay. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description goes well beyond the annotations, disclosing that it terminates in-flight deliveries, invalidates existing webhook payload records, and regenerates/resends them. It also adds the rate-limit detail. Nothing contradicts the destructiveHint=true or idempotentHint=false 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?
Three sentences with no filler: main action, use case, then critical warnings. The destructive behavior and rate limit are front-loaded in the same compact block, making the tool's risk profile immediately visible.
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 destructive, non-idempotent tool, the description discloses side effects, rate limiting, and appropriate invocation context. An output schema exists, so return-value documentation is not required here. The description is complete enough for an agent to call it safely with the provided 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?
Schema description coverage is 100%, with both searchBy and trackerId already documented inline. The description adds no new parameter-level detail beyond referring to 'a tracker,' so the baseline of 3 applies.
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?
Description opens with a specific verb+resource: 'Replays all webhook events for a tracker.' It clearly separates this from siblings like download_webhook_history by focusing on replay/resend rather than retrieval. The use case 'when your endpoint missed or failed to process previous notifications' further pins down the purpose.
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 states when to use: 'Use when your endpoint missed or failed to process previous notifications.' It also gives a clear when-not: 'do not call repeatedly in quick succession,' plus a rate-limit constraint. While it does not name an alternative sibling, the stated context is sufficient for an agent to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Default tool for one-off tracking lookups ('track X', 'where is my package'). Synchronous per-call plan endpoint: returns full results (status, events, statistics) immediately and creates NO tracker on the account. Billed per call. Requires an active per-call plan — if it fails with no_active_subscription, use the track tool instead.
| Name | Required | Description | Default |
|---|---|---|---|
| courierCode | No | Courier codes for this tracker (max 3). Use get_couriers for valid codes. IMPORTANT: Check each courier's requiredFields array — any listed fields should be provided, otherwise the courier may not return any tracking data. | |
| shippingDate | No | Date the package was shipped (YYYY-MM-DD or ISO 8601). | |
| trackingNumber | Yes | Tracking number to look up. 5-50 alphanumeric characters, hyphens, underscores, dots, or slashes. | |
| originCountryCode | No | Origin country code (ISO alpha-2). | |
| destinationPostCode | No | Destination postal/ZIP code. | |
| destinationCountryCode | No | Destination country code (ISO alpha-2). |
| Name | Required | Description |
|---|---|---|
| trackings | Yes | One entry per matched tracker or shipment. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint, openWorldHint), the description discloses key behaviors: synchronous execution, immediate full results, no tracker creation, per-call billing, and subscription dependency. This is exactly the kind of contextual behavior an agent needs and exceeds what annotations alone provide. No contradiction with 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?
Three tightly packed sentences: first defines purpose and typical use, second states behavioral outcome and billing model, third provides fallback. No filler; each sentence adds distinct value and the key differentiator is front-loaded.
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?
The output schema is present, so return details need not be spelled out. The description covers when to use, how it behaves, what side effects it avoids, cost implications, and what to do on failure. For a six-parameter tool, this is complete and actionable.
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 description coverage is 100%, with detailed parameter descriptions including format, constraints, and courier-specific validation notes. The tool description does not add parameter-level meaning, but the schema already handles it, so baseline 3 is appropriate.
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 verb and resource: one-off tracking lookups with natural-language examples ('track X', 'where is my package'). It explicitly differentiates from siblings by labeling itself 'Default tool' and clarifying it is a synchronous per-call endpoint that creates no tracker, making its role distinct from track and create_tracker.
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?
Usage guidance is explicit: it is the default for one-off lookups, and it provides a concrete routing rule for failure — if no_active_subscription occurs, use track instead. This gives an agent a clear decision boundary between search_tracking and its alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| trackingNumber | Yes | The raw shipment tracking number to search for (e.g. 1Z999AA10123456784). |
| Name | Required | Description |
|---|---|---|
| trackings | Yes | One entry per matched tracker or shipment. |
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.
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.
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.
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.
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.
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.
Creates a persistent tracker on the account AND returns full tracking results synchronously in one call (per-shipment plan). Idempotent: same payload reuses the existing tracker. Prefer search_tracking for one-off lookups when the per-call plan is available. If the returned shipment is still pending with no events, call get_tracking_results once with the returned trackerId before answering. Accepts the same fields as create_tracker — see that tool for field details.
| Name | Required | Description | Default |
|---|---|---|---|
| settings | No | ||
| courierCode | No | Courier codes for this tracker (max 3). Use get_couriers for valid codes. IMPORTANT: Check each courier's requiredFields array — any listed fields should be provided, otherwise the courier may not return any tracking data. | |
| courierName | No | ||
| orderNumber | No | ||
| trackingUrl | No | ||
| shippingDate | No | ||
| trackingNumber | Yes | ||
| clientTrackerId | No | ||
| originCountryCode | No | ||
| shipmentReference | No | ||
| destinationPostCode | No | ||
| destinationCountryCode | No |
| Name | Required | Description |
|---|---|---|
| trackings | Yes | One entry per matched tracker or shipment. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds meaningful behavior beyond annotations: it explains idempotency concretely ('same payload reuses the existing tracker'), discloses the persistent side effect, and describes the synchronous return behavior plus a conditional follow-up call. Annotations already include idempotentHint and destructiveHint, but the description enriches the agent's understanding of what happens during and after the call.
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 compact and front-loaded: core behavior first, then idempotency, then usage routing, then a conditional follow-up, then field delegation. Every sentence earns its place, and there is no redundant restatement of the name or title.
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 tool with 12 parameters and nested objects, the description wisely delegates field details to create_tracker and relies on the presence of an output schema for return semantics. It covers the key operational context: persistence, synchronous results, idempotency, and when to use an alternative. The phrase 'per-shipment plan' is slightly unexplained, but overall the agent has enough direction to call the tool correctly.
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 description coverage is only 8%, and the description does not explain any of the 12 parameters. It defers responsibility with 'Accepts the same fields as create_tracker — see that tool for field details,' which is a helpful pointer but not self-contained. An agent may need to fetch another tool's definition to understand parameters like courierCode, shippingDate, or clientTrackerId.
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 clearly states a specific behavior: 'Creates a persistent tracker on the account AND returns full tracking results synchronously in one call.' This goes beyond the tool name and titles, describing both the resource affected (persistent tracker) and the immediate outcome (tracking results), while also distinguishing it from the one-off search_tracking sibling.
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 explicit routing guidance: 'Prefer search_tracking for one-off lookups when the per-call plan is available.' It also provides a concrete follow-up instruction to call get_tracking_results when the shipment is pending with no events. It does not fully contrast track with create_tracker, but it points to create_tracker for field semantics, which indirectly clarifies the relationship.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Partially updates a tracker (PATCH). Only provided fields are changed. Common uses: toggling isSubscribed, correcting destination details, or setting a clientTrackerId.
| Name | Required | Description | Default |
|---|---|---|---|
| searchBy | No | How to interpret trackerId: default is Ship24 trackerId, use "clientTrackerId" for your own reference. | |
| settings | No | ||
| trackerId | Yes | The tracker to update (Ship24 trackerId or clientTrackerId). | |
| courierCode | No | Courier codes for this tracker (max 3). Use get_couriers for valid codes. IMPORTANT: Check each courier's requiredFields array — any listed fields should be provided, otherwise the courier may not return any tracking data. | |
| isSubscribed | No | true to subscribe to webhooks, false to unsubscribe. | |
| shippingDate | No | Ship date (YYYY-MM-DD or ISO 8601). Immutable once tracking data exists. | |
| originCountryCode | No | Origin country code (ISO alpha-2). Immutable once tracking data exists. | |
| destinationPostCode | No | ||
| destinationCountryCode | No | Destination country code (ISO alpha-2). Immutable once tracking data exists. |
| Name | Required | Description |
|---|---|---|
| tracker | Yes | The tracker. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral context beyond the annotations by explicitly stating that only provided fields are changed, reinforcing the PATCH semantics. The annotations already indicate non-destructive and idempotent behavior, so the description does not need to repeat safety details. It could mention immutability constraints, but those are already captured in the schema descriptions.
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 compact and front-loaded: it names the operation, the HTTP semantics, the partial-update rule, and common use cases in three short sentences. There is no filler or redundancy.
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?
The description is sufficient for an agent to understand the tool's role among its siblings, especially with the output schema and annotations available. It lacks explicit guidance on when to prefer update_tracker over create_tracker, but the partial-update framing and common-use examples cover most selection scenarios, and the schema handles parameter-level constraints.
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 description coverage is 78%, so most parameters are already documented in the schema. The description adds the general semantic that omitted fields remain unchanged, and hints at clientTrackerId usage, but it does not provide detailed parameter-level guidance beyond what the schema already offers.
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 'Partially updates a tracker (PATCH)', a specific verb plus resource that clearly identifies the operation and differentiates it from create/get/list siblings. It also clarifies the partial-update semantics and names concrete use cases such as toggling isSubscribed and correcting destination details.
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 clear context for when the tool is appropriate by listing common uses: toggling isSubscribed, correcting destination details, or setting a clientTrackerId. It does not explicitly name alternatives or say when not to use it, but the PATCH semantics and 'only provided fields are changed' make the intended scenario reasonably clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claiming proves that you control a remote MCP connector. It does not move, proxy, or interrupt the server.
Open the connector listing, choose Claim ownership, and sign in to Glama.
Complete one verification method:
GitHub identity — fastest for official registry listings. For a namespace such as io.github.alice/server, link the matching GitHub user or an account that owns the GitHub organization, then choose Claim with GitHub.
HTTP challenge — works when you can deploy a public file. Generate a token, publish the exact JSON Glama shows at /.well-known/glama.json on the same origin as the connector, then choose Check HTTP challenge.
DNS challenge — works when you control DNS but cannot change the server. Generate a token, create the exact TXT record Glama shows, wait for it to propagate, then choose Check DNS challenge.
After verification, Glama sends a confirmation email and gives you access to listing details, thumbnails, health checks, and analytics. Keep the HTTP file or DNS record in place: Glama periodically checks it and ownership remains verified while the token is discoverable.
The HTTP ownership file has this structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"claim": "glama_claim_..."
}Claim tokens are opaque, stable, and bound to the signed-in Glama account. They contain no email address or other personal information. If Glama can no longer discover a verified HTTP or DNS token, it starts a seven-day grace period before removing claim-based access. Restore the same token during that period to keep ownership verified. Never publish an email address, Glama session token, GitHub token, or connector credential as ownership proof.
If verification fails, confirm that you copied the current token exactly. The HTTP file must be public, return valid JSON with a successful HTTP response, and stay on the connector's origin. DNS changes may need more time to propagate. A claim cannot transfer to a different origin or hostname: if the connector target changes, Glama starts the grace period and the new target must be claimed separately after the previous claim is released.
For a connector linked to the official MCP Registry, registry updates continue to replace its name, description, and URL by default. After claiming, open Manage connector and enable Use Glama listing details as the source of truth if edits made on Glama should be preserved. Categories and thumbnails are always managed on Glama; registry linkage and technical connection settings continue to sync.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
To improve your MCP server's ranking:
Claim ownership of the server listing
Complete the server profile with an accurate description and thumbnail
Provide a test profile so Glama can connect to and evaluate the server
Keep tool definitions clear and complete to earn a high Tool Definition Quality Score (TDQS)
Route real usage through the Glama Gateway; more recorded successful server uses also improve the ranking
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
No comments yet. Be the first to start the discussion!
Track packages across 1,300+ global carriers with real-time status and AI-powered delivery dates.
Real-time order tracking for Shopify merchants: look up, list, and refresh shipments.
Auto-detect carrier from tracking number: USPS, UPS, FedEx, DHL, India Post, more.
DCSA container tracking across 228 ocean carriers: live vessel positions, ETAs, demurrage alerts.
Add one secure layer between your agents and this server.
Several tools appear to answer the same 'where is my package?' question: search_tracking, search_tracking_by_number, track, and get_tracking_results. The descriptions explain subtle differences around billing, persistence, and account state, but the tool boundaries are still easy to blur during selection.
Most tools follow a consistent snake_case verb_noun pattern such as create_tracker, get_tracker, list_trackers, update_tracker, and bulk_create_trackers. The bare verb 'track' breaks the pattern, and search_tracking_by_number is a bit awkward, but overall naming is predictable.
Twelve tools is a reasonable, well-scoped size for a tracking service covering tracker lifecycle management, batch creation, search, couriers, and webhook operations. The count feels justified rather than padded.
The surface covers create, get, list, update, bulk creation, search, and webhook history/replay, which is fairly comprehensive. However, there is no delete_tracker or equivalent removal tool, leaving a notable lifecycle gap for stopping or cleaning up trackers.
