Track parcels across 3000+ carriers with 17TRACK: register numbers, read tracking events and quota.
The last two health checks of this connector failed. If this server requires authentication, missing or expired test credentials may be the cause. A test profile lets Glama authenticate for health checks and discover tools; it is separate from your personal connections.
If you are the author, claim ownership, then add or update a test profile under Admin → Test Profile.
Scored across 9 tools
Each tool targets a distinct action on the tracking domain: registering, reading, listing, stopping, retracking, changing carrier/tag, checking quota, and real-time lookup. The register vs realtime_lookup boundary is clearly explained (register starts ongoing tracking, realtime is a one-off unregistered lookup), and get_tracking vs list_tracking_numbers are cleanly separated.
All tools share the track17_ prefix and snake_case verb_noun style (change_carrier, get_quota, register_numbers, stop_tracking, etc.). The lone single-verb 'retrack' fits naturally given there is no noun to attach and does not break the pattern.
9 tools is well-scoped for a tracking API, covering the full lifecycle without redundancy. Each tool earns its place with a distinct operation.
Coverage is strong: register, read, list, stop, retrack, change carrier/tag, quota, and real-time lookup form a near-complete lifecycle. Minor gaps exist around explicit deletion or notification/email configuration, but the core workflows are fully supported.
WRITE: assign a different carrier to registered tracking numbers (up to 10 per call), for example when auto-detection picked the wrong one. A number can change carrier at most 5 times, and a successful change can be charged as one shipment (see track17_get_quota). POST /changecarrier.
| Name | Required | Description | Default |
|---|---|---|---|
| changes | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=true, but the description adds material facts an agent cannot get from them: a 10-item per-call cap, a lifetime limit of 5 carrier changes per number, the billing consequence ('charged as one shipment'), and the underlying POST /changecarrier endpoint. Error/partial-failure behavior and retry semantics against the 5-change budget remain undisclosed.
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?
A single dense sentence, front-loaded with the operation class ('WRITE:'), then capability, limits, cost, and endpoint in descending order of importance. 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?
For a destructive, billable mutation with strong annotation coverage and no output schema, the description supplies the limits, cost, quota cross-reference, and transport detail an agent needs. It stops short of describing failure modes (e.g., what happens when the 5-change limit is exceeded or a number isn't registered) and any auth/prerequisite 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?
The description restates the per-call cap ('up to 10') that is already enforced by the schema's maxItems, so it adds little parameter-level meaning. It says nothing about what carrier codes are valid (carrier_new is an unenumerated integer) or when carrier_old is required beyond what the nested schema descriptions already state. With the reported 0% schema description coverage, more compensation was expected.
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 ('assign a different carrier to registered tracking numbers') and leads with a 'WRITE:' marker that instantly separates it from read siblings like track17_get_tracking or track17_realtime_lookup. The 'for example when auto-detection picked the wrong one' clause clarifies the scope of the operation. An agent can distinguish this from track17_change_tag without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a concrete trigger scenario ('when auto-detection picked the wrong one') and routes cost-checking to the sibling track17_get_quota. It does not state when NOT to use it (e.g., before registering numbers, or instead of track17_register_numbers), so it is clear context rather than full when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
WRITE: set the tag (your own label, max 100 characters) of a registered tracking number. It replaces the old tag. Free. POST /changeinfo.
| Name | Required | Description | Default |
|---|---|---|---|
| tag | Yes | The new tag (max 100 characters; an empty string clears it). | |
| number | Yes | Tracking number (5-50 letters, digits or hyphens). | |
| carrier | No | Carrier code; needed if the number is tracked under several carriers. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=true and idempotentHint=true, so the description's 'It replaces the old tag' only confirms the destructive/idempotent profile. It does earn credit for 'Free', which discloses the quota-cost implication (relevant given sibling track17_get_quota), and for the POST /changeinfo endpoint.
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, front-loaded with the WRITE marker and the core action; every clause (label definition, replacement behavior, cost, endpoint) earns its place. No filler or restated 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 mutation tool with no output schema and fully documented parameters, the description covers the key facts an agent needs: it overwrites, it is free, and the tag length limit. It stops short of describing failure modes (unregistered number, ambiguous carrier) but is otherwise complete.
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%, so the schema already explains the tag, number and carrier parameters in full. The description restates the label/100-character limit but adds no syntax or edge-case detail beyond the schema (e.g. the empty-string-clears behavior lives only in the schema). Baseline 3.
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 ('set the tag ... of a registered tracking number'), making it immediately distinguishable from sibling track17_change_carrier and track17_retrack. The 'WRITE:' prefix also signals the operation class without ambiguity.
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 'WRITE:' marker and 'It replaces the old tag' give implied context for when this mutation applies, but there is no explicit when-to-use versus alternatives and no stated prerequisite (e.g. the number must already be registered, or how it differs from track17_register_numbers). Usage is inferable rather than spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The account's tracking quota: total, used, remaining, used today, the daily registration limit (0 = no limit) and the free e-mail quota. Each registered tracking number uses 1 quota. POST /getquota.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, so safety is covered. The description adds genuinely useful semantics beyond that: the 0 = no limit convention for the daily registration limit and the 1-quota-per-number accounting rule, plus the POST /getquota endpoint. It does not mention auth requirements, which is the only notable omission.
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 compact sentences, front-loaded with the resource and then the return fields, with zero filler. The '0 = no limit' clarification earns its place because it prevents a misreading of the returned 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?
With no output schema, the description carries the full burden of describing the response, and it does so by enumerating every returned field and explaining the two non-obvious ones (daily limit sentinel, quota cost). Nothing an agent needs to invoke or interpret this call 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 takes zero parameters, so per the rubric this is a baseline 4; there is nothing for the description to disambiguate. No parameter guidance is needed or expected here.
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 the exact resource and enumerates the returned values (total, used, remaining, used today, daily limit, free e-mail quota), so the agent knows precisely what this call yields. No other sibling deals with quota, making differentiation unambiguous.
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 is implied rather than stated: 'Each registered tracking number uses 1 quota' hints at checking quota before registering, but the description never says when to call it or contrasts it with track17_register_numbers or the other siblings. Adequate but with a clear gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full tracking details (status, sub-status, milestones, every carrier event with time and location, estimated delivery) for up to 10 numbers that are ALREADY registered on this account. Free: it does not use quota. A number that is not registered comes back in rejected — register it first with track17_register_numbers, or use track17_realtime_lookup. POST /gettrackinfo.
| Name | Required | Description | Default |
|---|---|---|---|
| numbers | Yes | Registered numbers, each with an optional carrier code (needed if the number is tracked under several carriers). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description adds genuinely new behavior: it is free and consumes no quota, it caps at 10 numbers, and unregistered numbers fail softly into a `rejected` bucket rather than erroring. It does not discuss rate limits or response envelope shape, so it stops short of a 5.
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?
Dense and front-loaded: the payload contents come first, then the registration constraint, then the free/quota fact and the fallback alternatives. Nearly every clause carries weight, though the trailing 'POST /gettrackinfo' endpoint token is implementation trivia that adds nothing for an agent choosing a tool.
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?
There is no output schema, but the description compensates by enumerating the returned fields, and the annotations carry the read-only/open-world safety profile. With quota cost, batch limit, and failure semantics all stated, an agent has everything needed to call this 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 100% and there is a single parameter, so the schema already documents the array, the per-item carrier code, the pattern, and the maxItems=10 cap. The description restates the 10-number limit and the 'carrier needed if tracked under several carriers' nuance, which the schema also states, adding little beyond the structured fields. Baseline 3 is correct.
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 and enumerates exactly what is returned (status, sub-status, milestones, carrier events with time/location, ETA) for a bounded set of up to 10 registered numbers. It explicitly distinguishes itself from track17_register_numbers and track17_realtime_lookup, so an agent can route correctly without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit precondition (numbers must ALREADY be registered), the failure mode when it is violated (the number comes back in `rejected`), and two concrete alternatives with the condition that selects each — register first, or use realtime_lookup. This is the full when/when-not/alternative triad.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the tracking numbers registered on this account (40 per page) with their carrier, status, registration and last-update times, and latest event. Filter by number(s), carrier, tracking state, package status or registration date. Free: it does not use quota. POST /gettracklist.
| Name | Required | Description | Default |
|---|---|---|---|
| carrier | No | 17TRACK numeric carrier code (for example 3011 = China Post, 100003 = FedEx). Full list: https://res.17track.net/asset/carrier/info/apicarrier.all.json | |
| numbers | No | Only these tracking numbers (up to 200). | |
| page_no | No | Page number, from 1 (omit for the first page). Use the reply's next_page. | |
| order_by | No | Sort order. | |
| data_origin | No | How the number was added. | |
| package_status | No | Only packages in this main status. | |
| tracking_status | No | Only numbers currently being tracked, or stopped. | |
| register_time_to | No | Registered on or before this date (yyyy-mm-dd). | |
| register_time_from | No | Registered on or after this date (yyyy-mm-dd). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=true, destructiveHint=false), so the description only needs to add operational context — and it does: 40 results per page, next_page pagination, zero quota cost, and the POST /gettracklist endpoint. This is meaningful information beyond the 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 compact sentences, purpose and pagination front-loaded, followed by filters and the quota note; little waste. The listing of returned fields is slightly dense but earns its place since there is no output schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description usefully describes the fields returned, the 40-per-page paging behavior, and the cost profile, which is enough for correct invocation. Missing only explicit routing guidance against the sibling tools that overlap in purpose.
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%, so the schema already fully documents all nine parameters, including carrier codes, enum values and date formats. The description only restates the filter categories (carrier, state, package status, registration date) without adding syntax or format detail, so baseline 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?
States a specific verb and resource — search tracking numbers registered on this account — and enumerates the returned fields (carrier, status, registration/last-update times, latest event). This clearly separates it from single-number siblings like track17_get_tracking and track17_realtime_lookup, though no sibling is named explicitly.
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 usable context: the filter axes available (number, carrier, tracking state, package status, registration date) and the important cost note that it is free and does not consume quota, which helps an agent pick it over quota-burning alternatives. No explicit when-not or named alternative is given, so it stops short of 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
WRITE (uses quota): look up ONE tracking number directly at the carrier right now, without registering it. Costs 1 quota per call (standard: carrier data up to 3 hours old). If the number is already registered, a changed result is also pushed to the account. Not supported for USPS, Royal Mail, Australia Post, Direct Freight Express, DHL eCommerce US and DHL Global Forwarding; some accounts are not enabled for real-time lookups. POST /getRealTimeTrackInfo.
| Name | Required | Description | Default |
|---|---|---|---|
| number | Yes | Tracking number (5-50 letters, digits or hyphens). | |
| carrier | No | 17TRACK numeric carrier code (for example 3011 = China Post, 100003 = FedEx). Full list: https://res.17track.net/asset/carrier/info/apicarrier.all.json | |
| ship_date | No | A date, yyyy-mm-dd. | |
| phone_number_last_4 | No | Last 4 digits of the recipient phone, for carriers that require it. | |
| destination_postal_code | No | Recipient postal code, for carriers that require it. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations: quantifies the cost (1 quota per call), discloses data staleness (up to 3 hours old), warns of a side effect (a changed result is pushed to the account), and lists the carriers and account configurations where it silently will not work. That is exactly the operational context the destructiveHint/readOnlyHint flags cannot convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the critical WRITE-quota warning, then constraints and the endpoint. Dense but every sentence carries information; no filler. The long unsupported-carrier list is somewhat bulky but is genuinely decision-relevant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the burden of describing results, and it only implies an answer plus a possible account push rather than describing the returned fields or a 'not found' case. Everything an agent needs before calling — cost, side effects, unsupported cases — is present.
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 all five parameters are already documented with patterns and examples, which sets the baseline at 3. The description adds only the 'one number per call' cardinality constraint and does not explain when the conditional parameters (carrier, ship_date, phone_number_last_4, destination_postal_code) become mandatory.
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 ('look up ONE tracking number directly at the carrier right now, without registering it') and immediately distinguishes itself from the registration path used by track17_register_numbers. The 'ONE' and 'without registering' phrasing separates it cleanly from list/get 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?
Explains the selecting conditions well: use it for an ad-hoc single-number lookup that should not be registered, and notes it is not supported for listed carriers or accounts not enabled for real-time lookups. It stops short of explicitly naming alternatives such as track17_register_numbers or track17_get_tracking for persistent tracking.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
WRITE (uses quota): start tracking up to 10 tracking numbers per call. Each ACCEPTED number costs 1 quota from this account (see track17_get_quota); rejected numbers cost nothing. Deleting and re-registering a number costs again. 17TRACK then updates the status itself every 6-12 hours; read it with track17_get_tracking. The carrier is detected automatically unless a carrier code is given. No e-mail notifications are enabled. POST /register.
| Name | Required | Description | Default |
|---|---|---|---|
| numbers | Yes | 1-10 numbers to register. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare the safety profile (readOnlyHint=false, destructiveHint=true, idempotentHint=false), and the description adds substantial context beyond that: quota consumption per accepted number, zero cost for rejects, cost on delete-and-re-register, automatic carrier detection, 6-12h self-refresh, disabled e-mail notifications, and the POST endpoint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the critical 'WRITE (uses quota)' marker, then packs only decision-relevant facts into tightly constructed sentences with no filler; 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?
For a mutation tool with no output schema, the description covers cost, quota, carrier resolution, refresh cadence, and the read path, so an agent has nearly everything needed. It could say a bit more about the per-number response shape (e.g., what a rejection looks like), but the gaps are minor.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema by stating the carrier is auto-detected unless a carrier code is supplied and by tying the array to the 10-number cap. This clarifies behavior of the carrier field that the schema only enumerates.
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+resource ('start tracking up to 10 tracking numbers per call') and is immediately distinguishable from siblings by naming track17_get_tracking and track17_get_quota. An agent knows exactly what this does without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Clearly routes the agent: check costs via track17_get_quota and read status via track17_get_tracking, and explains the cost economy of accepted vs rejected numbers. It stops short of explicitly contrasting with track17_retrack (re-registration) or track17_realtime_lookup, so it is clear context but not full when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
WRITE: restart tracking of stopped numbers (up to 10 per call). Each number can be restarted only ONCE in its lifetime, so a second restart is rejected. POST /retrack.
| Name | Required | Description | Default |
|---|---|---|---|
| numbers | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish the safety profile (readOnlyHint=false, destructiveHint=true, openWorldHint=true), so the description's job is to add specifics — and it does: a 10-per-call cap and a hard one-restart-per-lifetime limit with rejection on retry. The rejection behavior is consistent with idempotentHint=true in that repeat calls produce no further state change, so no contradiction. It does not mention authentication, quota impact, or response shape.
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, all front-loaded: the operation and its scope first, then the constraints, then the endpoint. No filler, and each sentence carries a distinct piece of information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter write tool with no output schema, the description covers operation, limit, failure mode, and transport. What is missing is any hint of the response or what a rejected restart looks like to the caller, which an agent would have to discover empirically.
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?
Top-level schema coverage is 0% for the 'numbers' array, though the nested 'number' and 'carrier' fields are documented inline in the schema. The description compensates only partially by restating the batch ceiling ('up to 10 per call'), which matches maxItems, and says nothing about the number/carrier object shape or that carrier is optional.
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 ('restart tracking') and names the scope ('stopped numbers'), which cleanly separates it from stop_tracking, register_numbers, and change_carrier. The 'WRITE:' prefix and POST /retrack endpoint make the operation unambiguous.
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 precondition ('stopped numbers') tells the agent when this tool applies, and the once-per-lifetime rule warns when it will fail. It stops short of naming alternatives explicitly (e.g., use register_numbers for never-tracked numbers), so the routing guidance is contextual rather than spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
WRITE: stop tracking registered numbers (up to 10 per call). The numbers stay in the account for 90 days with their history and can be restarted ONCE each with track17_retrack. Stopping does not refund quota. POST /stoptrack.
| Name | Required | Description | Default |
|---|---|---|---|
| numbers | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=true, and the description adds the consequences those hints cannot express: numbers persist 90 days with history, are restartable exactly once, and quota is not refunded. This is exactly the before-you-commit context an agent needs.
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 short fragments, front-loaded with the WRITE marker and the batch cap, then retention rules and the endpoint. No sentence is 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?
Covers scope, limits, side effects, reversibility and endpoint for a single-parameter tool with no output schema. It omits only failure/partial-batch behavior, which is a minor gap given the annotation coverage.
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 description conveys the maxItems=10 constraint and confirms the payload is a list of tracking numbers, but says nothing about the optional carrier field or the accepted number format. With reported schema description coverage at 0% for the top-level parameter, this only partially compensates.
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 ('stop tracking registered numbers'), marks it as a WRITE operation, and quantifies the batch limit. It is immediately distinguishable from siblings like track17_register_numbers and track17_retrack.
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 names the alternative path (track17_retrack) and the condition under which it applies ('can be restarted ONCE each'), plus the caveat that stopping does not refund quota. It stops short of stating when NOT to stop tracking (e.g., use list_tracking_numbers first) but gives clear selection context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Track parcels across 2,500+ carriers and 3PLs: live delivery status, event history, carrier lookup.
Track parcels with TrackingMore: detect couriers, create and read trackings, delivery status.
Track packages across 1,300+ global carriers with real-time status and AI-powered delivery dates.
Track 542 carriers (USPS, UPS, FedEx, UniUni, LTL) via MCP, API, Webhooks & Watches.
Add one secure layer between your agents and this server.
