Read Starshipit orders, tracking, rates and manifests; create and update unshipped orders.
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 19 tools
The order-listing tools overlap substantially: list_orders (status-filtered), list_unshipped_orders, list_shipped_orders, list_printed_orders, list_delivered_orders, orders_summary and search_orders all return order sets and their boundaries require careful reading. The descriptions do explain the differences (compact vs full, status-specific, query-based), which rescues it from being truly confusing, but an agent can still easily pick the wrong one.
Nearly all tools follow starshipit_ + verb_noun snake_case (get_order, create_order, update_order, list_address_book), which is predictable. Minor deviations (orders_summary has no verb, and add_order_tags vs create_order use different verbs for write actions) keep it from a perfect score.
19 tools is on the heavier side but the surface spans several genuinely distinct sub-domains (orders, rates/delivery services, address book, products, tags, manifests, pickups, tracking), so most tools earn their place. The main count inflation comes from the multiple order-status listing tools, which could be consolidated.
Core order read/write (create, get, update, list, search, tag, track) is covered well, but several lifecycle operations are explicitly absent: label printing, manifesting, pickup booking, and order deletion/cancellation are all noted as 'not available here.' These gaps are plausible scope decisions but leave dead ends for common workflows.
WRITE: add up to 10 tags to ONE UNSHIPPED order (read first; refused if printed or shipped) (a tag that does not exist yet is created). Tags are used for filtering and can drive the account's automation rules. Adding a tag the order already has changes nothing. Tags are not removed. POST /api/tags/order.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | Yes | Tag names to add (1-10). | |
| order_id | Yes | Starshipit order id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations: it discloses that missing tags are auto-created, that re-adding an existing tag is a no-op, that tags are never removed, and that tags can trigger the account's automation rules. That last point is meaningful side-effect context not implied by destructiveHint/openWorldHint alone.
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?
One front-loaded, densely packed sentence with the operation mode ('WRITE') and the target constraint first, followed by a short endpoint. No filler or restatement of the 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?
Covers preconditions, side effects, and idempotency for a two-parameter mutation with no output schema. The only gap is what comes back on success (e.g. updated tag list), which an agent would have to infer.
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 semantics: the 10-tag ceiling, one-order scoping, and the side effect that unknown tag names are created rather than rejected. Length limits and the integer order id are left to the schema.
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?
Opens with a specific verb-plus-resource-plus-scope: 'WRITE: add up to 10 tags to ONE UNSHIPPED order'. The UNSHIPPED qualifier and the 'a tag that does not exist yet is created' clause distinguish it sharply from siblings like starshipit_update_order or starshipit_get_order.
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?
States both the positive case (unshipped order) and the negative case ('refused if printed or shipped'), plus the workflow prerequisite 'read first'. Although no sibling is named as an alternative, the when/when-not guidance is unusually explicit for a tag operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
WRITE: create ONE new UNSHIPPED order in Starshipit (order number, destination, optional items, parcels, sender). No label is printed, no shipment is booked and no postage is bought; staff still print the label in Starshipit. Not idempotent: creating the same order_number twice may create a duplicate, so check with starshipit_search_orders first. Starshipit rules configured in the account (carrier selection, validation) may run on the new order. POST /api/orders.
| Name | Required | Description | Default |
|---|---|---|---|
| items | No | ||
| carrier | No | Starshipit carrier code, e.g. AusPost (optional; rules may choose one). | |
| currency | No | Currency code of the item values, e.g. AUD. | |
| packages | No | ||
| reference | No | Customer reference (max 50 chars). | |
| destination | Yes | ||
| order_number | Yes | Order number from the source system (max 50 chars). | |
| return_order | No | true = a return order (only the return label will be generated later). | |
| sender_details | No | Sender; omitted = the account's pickup address. | |
| shipping_method | No | Delivery method name, e.g. Express Shipping. | |
| signature_required | No | ||
| carrier_service_code | No | Carrier service code from a rates quote, e.g. 7B05. | |
| shipping_description | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint=false, idempotentHint=false, destructiveHint=true), it clarifies the actual blast radius: no label printed, no shipment booked, no postage bought, and that account-level rules (carrier selection, validation) may run. It also explains the duplicate-creation consequence of the non-idempotency hint and names 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-loaded with 'WRITE:', then packed with distinct, non-redundant facts across three tight sentences. Nothing is padding and the most decision-relevant scoping ('UNSHIPPED', non-idempotent) comes first.
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 13-parameter, nested-object create tool with no output schema, the description covers purpose, side-effect scope, idempotency risk and rules behavior. The remaining gap is that it says nothing about what the call returns (e.g. the created order identifier) and leaves part of the parameter surface to the 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 62% and the description only restates the top-level axes (order number, destination, items, parcels, sender) without adding format or semantics. It neither compensates for the undocumented parameters nor would be needed given what the nested schema already carries.
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 ('create ONE new UNSHIPPED order in Starshipit') and enumerates the payload axes (order number, destination, items, parcels, sender). The 'UNSHIPPED' scope distinguishes it from list_shipped_orders, get_rates and update_order 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 names an alternative and the condition that selects it: 'check with starshipit_search_orders first' because the call is not idempotent. Clear context for safe invocation, though it does not contrast against siblings like update_order or add_order_tags.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One order by Starshipit order_id or by the order_number from the source platform. Use include to add sections (Items, Packages, Events, Metadatas, Shipping_Price, ...). Status defaults to Unshipped in Starshipit, so pass status=Shipped or Printed for orders already printed. Label files are not returned. GET /api/orders?order_id= or ?order_number=.
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | Order status to look in (Starshipit default: Unshipped). | |
| include | No | Extra sections to include. | |
| order_id | No | Starshipit order id. | |
| order_number | No | Order number from the source platform, e.g. #1234. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It usefully discloses the default Unshipped status filtering behavior and that label files are excluded, but is silent on auth requirements, pagination, error/no-match behavior, and the shape of the returned order object.
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, front-loaded sentences with no filler; the lookup keys come first, then the param guidance and the limitation. The raw HTTP endpoint string contributes little for an MCP caller, which is the only genuinely dispensable clause.
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, so the description must stand in for return-value information, and it only says labels are absent. Combined with the undocumented order_number parameter and unstated failure modes, it is adequate but has clear gaps for an agent that needs to know what it will actually get back.
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 partial (status and include are documented, order_id is not), and the description mostly repeats those schema descriptions. Its main added value is identifying order_id as the Starshipit id and order_number as a source-platform key, though order_number does not appear in the input schema at all, which creates ambiguity about whether that lookup is actually usable.
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 (one order) and both lookup keys (Starshipit order_id or source-platform order_number), plus the underlying endpoint. The singular scope implicitly separates it from the galaxy of list_*/search_orders siblings, but 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 genuine caller guidance: use 'include' to pull extra sections, and pass status=Shipped/Printed when the order was already printed because the Starshipit default of Unshipped will hide it. It also flags a limitation ('Label files are not returned'). No explicit comparison to alternatives such as search_orders or list_unshipped_orders.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
QUOTE ONLY: shipping rates (service name, code, price) for a destination and parcels from the couriers enabled in the account. Nothing is purchased, created or printed. The sender defaults to the account's pickup address. Needs at least one enabled courier. POST /api/rates.
| Name | Required | Description | Default |
|---|---|---|---|
| sender | No | Sender address; omitted = the account's pickup address. | |
| currency | No | Currency code for the order value, e.g. AUD. | |
| packages | Yes | The parcels (weight in kg, dimensions in metres). | |
| destination | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this with 'Nothing is purchased, created or printed', so there is no contradiction. It adds useful operational context (account pickup default, courier prerequisite, endpoint) beyond the annotations, though it doesn't cover rate behavior like carrier response variance or error 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?
Front-loads the critical 'QUOTE ONLY' constraint, then layers returned fields, side-effect exclusions, defaults, and prerequisite in tight sentences with no filler. Every sentence carries distinct 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 nested-parameter quoting tool with no output schema, the description names the return fields and the read-only guarantee, making it callable without guessing. Minor remaining gap is the unmentioned currency parameter, but overall it is nearly 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 75%, so the schema already documents most fields including units and the sender default. The description adds little beyond restating destination, parcels, and the sender default that the schema already carries, and never mentions the currency parameter.
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 (quote) and resource (shipping rates), spells out what is returned (service name, code, price), and scopes it to a destination, parcels, and account-enabled couriers. This clearly distinguishes it from the order-mutating siblings like starshipit_create_order.
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?
'QUOTE ONLY' plus 'Nothing is purchased, created or printed' tells the agent exactly when this applies versus a create tool, and 'Needs at least one enabled courier' gives a prerequisite. It stops short of naming an explicit alternative tool, but the exclusion of write behavior is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List contacts in the account's address book (name, company, address, phone, email), sorted by a column. GET /api/addressbook/filtered.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number, from 1 (default 1). Pass the previous reply's next_page. | |
| sort | No | ||
| page_size | No | Contacts per page, 1-250 (default 50). | |
| sort_direction | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds useful context by naming the returned fields and stating results are sorted, but says nothing about pagination limits or what happens at the end of the result set.
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 front-loaded sentence covering resource, returned fields, ordering, and the underlying endpoint. Every clause carries information and nothing is padded.
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, enumerating the returned contact fields in the description is genuinely valuable. It is nearly complete for a read-only list tool, though it omits the pagination/next_page continuation behavior that the schema alludes to.
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 50%: page and page_size are documented in the schema, while sort and sort_direction are enum-only and self-explanatory. The description's phrase 'sorted by a column' hints at the sort parameter but adds no format or default details beyond the schema, so the 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 (List) and resource (contacts in the account's address book), and enumerates the fields returned. No sibling tool touches the address book, so an agent can immediately tell this apart from the order/shipment tools in the namespace.
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 implies the use case (retrieve address book contacts) but offers no explicit when-to-use, prerequisites, or alternatives. Since there is no competing sibling for this resource, the missing routing guidance is less costly, but the guidance is still only implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List delivered orders that carry a given order reference (the customer reference), with full order details. GET /api/orders/delivered.
| Name | Required | Description | Default |
|---|---|---|---|
| order_ref | Yes | The order reference to look for. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, destructiveHint=false, and openWorldHint, so the safety profile is covered. The description adds that results include 'full order details' and exposes the endpoint, but says nothing about pagination, result caps, or authentication needs. Some value added, but modest beyond 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?
Two compact sentences, front-loaded with the filter and result scope. The trailing 'GET /api/orders/delivered' is low-value implementation detail an agent can't act on, a small 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?
For a single-parameter read tool with full annotation coverage, the description covers what it returns ('full order details') and what it filters on. However, it omits pagination or result-limit behavior and whether partial matches are returned, which matter for a list tool.
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 baseline is 3, but the description genuinely clarifies an ambiguous parameter: it specifies that order_ref means the *customer* reference, not an internal order id. That disambiguation adds meaning beyond the schema's terse 'The order reference to look for.'
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 ('List'), resource ('delivered orders'), and filter ('carry a given order reference'), plus the return scope ('full order details'). The 'delivered' qualifier naturally distinguishes it from siblings like list_orders and list_shipped_orders, though it never names an alternative 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?
The description implies you call it to find delivered orders for a reference, but gives no explicit when-to-use guidance and never contrasts it with close siblings such as search_orders, list_orders, or get_order. The agent has to infer the selection condition.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
QUOTE ONLY: the carrier delivery services available for a shipment (carrier, service name and code) and, with include_pricing, their prices and service options. Nothing is purchased, created or printed. POST /api/deliveryservices.
| Name | Required | Description | Default |
|---|---|---|---|
| sender | No | Sender address; omitted = the account's pickup address. | |
| packages | Yes | The parcels (weight in kg, dimensions in metres). | |
| destination | Yes | ||
| return_order | No | ||
| declared_value | No | Value of the shipment. | |
| dangerous_goods | No | ||
| include_pricing | No | Return prices (default false). | |
| insurance_value | No | ||
| authority_to_leave | No | ||
| signature_required | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false; the description adds genuine value by clarifying that the POST /api/deliveryservices call is a query ('QUOTE ONLY', 'Nothing is purchased, created or printed'), which resolves the confusion of a read operation exposed as POST. It also discloses the include_pricing behavior. No return format or pagination detail, but the safety profile is well covered.
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 front-loaded sentences with no filler; 'QUOTE ONLY' leads with the key constraint. The trailing endpoint path earns its place by flagging the POST semantics, though it could be woven in more cleanly.
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 10-parameter tool with nested sender/destination/packages objects and no output schema, the description covers purpose and the read-only nature but is thin on how the required shipment inputs (destination, packages) shape the result and on the many optional flags. Adequate as a minimum-viable definition, but not complete for the complexity.
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?
With 40% schema description coverage across 10 parameters, the description is expected to compensate, but it only addresses include_pricing (already documented in the schema) and gestures at the shipment via 'for a shipment'. It says nothing about sender, return_order, declared_value, dangerous_goods, insurance_value, authority_to_leave or signature_required, leaving six-plus parameters unexplained in both places.
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 (list/quote) and resource (carrier delivery services available for a shipment), and enumerates what is returned (carrier, service name and code). It separates itself from write tools by asserting nothing is purchased/created/printed, though it never names the closest sibling (get_rates). Clear and specific, but no explicit sibling differentiation.
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 'available for a shipment' framing and the include_pricing toggle imply this is a pre-order quoting step, but it never states when to use it instead of get_rates or the create_order flow. Usage is inferable rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List manifests already submitted to carriers (newest first): number, date, carrier, package and consignment counts. Read only; manifesting is not available here. GET /api/manifests.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number, from 1 (default 1). Pass the previous reply's next_page. | |
| limit | No | Results per page, 1-250 (default 50). |
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 value by disclosing sort order (newest first), the field set returned, the backing endpoint (GET /api/manifests), and an explicit boundary that manifest creation is not available here. It does not mention pagination behavior, though the schema's next_page reference implies it.
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?
One compact sentence carries purpose, scope, ordering, and return fields, with the scope constraint front-loaded; the read-only/negative clause follows immediately. Nothing is padded.
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 enumerates the returned fields (number, date, carrier, package/consignment counts), which is exactly the compensation needed. Two optional params are schema-documented. Only pagination semantics are left entirely to the schema, a minor gap for a simple list tool.
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% — page and limit are fully documented in the schema, including defaults and the next_page chaining pattern. The description adds no syntax or format detail beyond that, so the 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 ("List manifests"), a precise scope ("already submitted to carriers"), ordering ("newest first"), and the returned fields (number, date, carrier, counts). An agent can distinguish this from every sibling listing tool (orders, pickups, products, tags) without opening a 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?
The scope phrase "already submitted to carriers" combined with "Read only; manifesting is not available here" implies when this applies (reviewing submitted manifests) and rules out a write-oriented expectation. However, it names no alternative tool or condition for choosing between this and, say, list_pickups; usage is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List full order details for one status (Unshipped by default, or Shipped / Printed), narrowed by a filter such as Order:::1419,Country:::Australia and sorted. Heavier than the summary: use starshipit_orders_summary for overviews. Label files are not returned. GET /api/orders (no id).
| Name | Required | Description | Default |
|---|---|---|---|
| filter | No | Filter string COLUMN:::VALUE, several separated by commas, e.g. `Order:::1419,State:::NSW` or `Source:::Shopify`. Columns: Order, Name, Address (valid), Date (>=MAY 2024), Source, State, Country, Carrier, Service, Status, SKU, SingleSKU, Writeback, Weight (>=5), ShippingMethod, ShippingDescription, Tag. Prefix a column with ! to negate (!Country:::Australia). | |
| status | No | Order status (default Unshipped). | |
| include | No | Extra sections to include. | |
| page_size | No | Results per page, 1-100 (default 25). | |
| page_number | No | Page number, from 1 (default 1). Pass the previous reply's next_page. | |
| sort_column | No | ||
| sort_direction | No |
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 goes further by disclosing a negative output trait ('Label files are not returned') and a cost/weight trade-off versus the summary tool. It still doesn't describe pagination behavior or rate limits, keeping it 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?
Three dense sentences, front-loaded with the core purpose before the alternative-tool pointer and the output caveat; virtually no filler. Slightly packed with clause-level detail, but every sentence 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?
With no output schema, the description carries the return-value burden and partially does so ('full order details', labels excluded, next_page pagination). It covers status scoping, filtering, sorting and paging adequately for a 7-parameter list tool, though it never sketches the response shape beyond 'full order details'.
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 71%, so most parameters are already documented in the schema (filter syntax, status default, page_size, page_number with next_page hint). The description restates the filter example and default status but adds nothing new for include, sort_column, or sort_direction. Baseline 3 for partial-coverage schemas 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?
States a specific verb+resource ('List full order details'), its scope constraint ('for one status'), and the underlying endpoint 'GET /api/orders (no id)' which separates it from starshipit_get_order. It also explicitly names the sibling it is heavier than, starshipit_orders_summary, so the agent can route 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 alternative and the condition that selects it ('Heavier than the summary: use starshipit_orders_summary for overviews'), which is real routing guidance. It does not address the closely-named siblings starshipit_list_unshipped_orders / list_shipped_orders / list_printed_orders or starshipit_search_orders, though the 'one status' framing implicitly covers the former.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List courier pickups already booked for the account. Read only; booking a pickup is not available here. GET /api/pickup.
| Name | Required | Description | Default |
|---|---|---|---|
| page_size | No | Pickups per page, 1-250 (default 50). | |
| page_number | No | Page number, from 1 (default 1). Pass the previous reply's next_page. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description usefully reinforces read-only and adds that booking is unavailable here, but says nothing about pagination behavior or how results are ordered, which the schema alone only partly hints at.
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 purpose, then the read-only constraint, then the endpoint. No filler and nothing buried.
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 two-parameter paginated list with no output schema and annotation-covered safety, the description plus schema give an agent enough to invoke correctly; the pagination contract lives in the schema. It could go slightly further by noting what a pickup record contains or any default filters, but 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?
Schema description coverage is 100%: page_size and page_number both carry inline documentation including defaults and the instruction to pass the previous reply's next_page. The description adds no parameter meaning beyond that, so the 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 (List) and resource (courier pickups already booked for the account), and scopes it to existing bookings rather than creation. No sibling lists pickups, so no differentiation is required, and the added 'GET /api/pickup' pins the exact operation.
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?
'Read only; booking a pickup is not available here' explicitly marks the boundary of when not to expect write behavior, which steers the agent away from a nonexistent booking tool. It stops short of naming an alternative tool or the conditions under which this list is the right choice (e.g., date filtering does not exist here).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List orders whose label was recently printed, or printed but not yet manifested, with tracking numbers. GET /api/orders/shipments.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number, from 1 (default 1). Pass the previous reply's next_page. | |
| limit | No | Results per page, 1-250 (default 50). | |
| status | No | Which shipments to list (default recently_printed). | |
| since_created_date | No | Only shipments created after this UTC date-time (RFC 3339). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds modestly useful context: results include tracking numbers, and it exposes the underlying GET /api/orders/shipments endpoint. It does not mention pagination behavior or auth needs, which is acceptable given the annotation coverage.
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 tight sentence plus the endpoint: the verb and scope are front-loaded and every clause earns its place. 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?
For a low-complexity, zero-required-parameter list tool with 100% schema coverage and clear read-only annotations, the description covers scope, the two modes, included tracking numbers, and the endpoint. Without an output schema it could say slightly more about the return shape, but it is largely complete for the complexity level.
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 page, limit, status and since_created_date are fully documented in the schema; the baseline is 3. The description only restates the two status modes already captured by the enum, adding no syntax or format detail beyond the structured fields.
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 ('List orders') and a precise scope (label recently printed, or printed but not yet manifested), matching the two status enum values. This clearly distinguishes a 'printed' scope from related lists. However, it never names a sibling (e.g. list_shipped_orders, list_manifests) to route against, so differentiation is implicit rather than explicit.
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?
There is no guidance about when to choose this tool over the many sibling list tools (list_orders, list_shipped_orders, list_manifests, list_unshipped_orders). The description describes what the tool returns but gives no conditions, prerequisites, or exclusions for selection. Usage must be inferred entirely from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List Product Catalogue records (SKU, title, weight, dimensions, HS code, bin location, price), optionally searching by SKU or title. GET /api/products.
| Name | Required | Description | Default |
|---|---|---|---|
| page_size | No | Products per page, 1-250 (default 50). | |
| page_number | No | Page number, from 1 (default 1). Pass the previous reply's next_page. | |
| search_term | No | Search text for SKU or title. | |
| sort_column | No | Column to sort by (default Sku). | |
| sort_direction | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the underlying endpoint (GET /api/products) and the returned field set, which is useful, but says nothing about pagination behavior, result caps, or rate limits.
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 short sentences with zero waste. The resource and returned fields are front-loaded, and the search capability follows immediately; the endpoint note is a compact factual tag rather than 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?
With no output schema, the description usefully enumerates the returned fields, compensating for the missing return documentation, and pagination is covered by the schema's page_size/page_number descriptions. Only minor gaps remain, such as total-count or sorting behavior nuances.
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 80%, so page_size, page_number, search_term and sort_column are already documented in the schema. The description only restates the search capability, adding no syntax or format detail beyond what the schema provides; 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?
States a specific verb and resource ('List Product Catalogue records') and enumerates the fields returned (SKU, title, weight, dimensions, HS code, bin location, price). It is the only product-catalogue tool among the siblings, so an agent can route to it unambiguously.
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 phrase 'optionally searching by SKU or title' implies the search use case but gives no explicit when-to-use or when-not-to-use guidance, and no alternative tool is named. Since this is the sole product tool there is no sibling conflict, but usage is still left implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List shipped orders (label printed) with tracking number, tracking status, carrier, manifest and shipped date. By default only orders updated in the last 24 hours; use since_last_updated to look further back. Label files are not returned. GET /api/orders/shipped.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number, from 1 (default 1). Pass the previous reply's next_page. | |
| limit | No | Results per page, 1-250 (default 50). | |
| ids_only | No | Return only the shipped order ids. | |
| since_last_updated | No | Only orders updated after this UTC date-time (RFC 3339). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds real behavioral context beyond them: the implicit 24-hour recency window, the fact that label files are deliberately not returned, and the underlying GET /api/orders/shipped 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 tight sentences plus an endpoint reference, with the highest-value information (what is returned, default time window) front-loaded. 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?
With no output schema, the description usefully pre-announces the returned fields and the notable omission (label files), and annotations cover read-only safety. Pagination and next_page handling are only implied via the schema, so coverage is strong but not exhaustive.
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 baseline is 3, but the description genuinely extends since_last_updated by disclosing that omitting it yields only the last 24 hours of updates — a default not stated in the schema. Pagination and ids_only are left entirely to the schema, keeping this below a 5.
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 ('List shipped orders') and enumerates the returned fields (tracking number, tracking status, carrier, manifest, shipped date), plus the parenthetical '(label printed)' that clarifies what 'shipped' means here. It does not explicitly contrast itself with close siblings such as list_printed_orders or list_unshipped_orders, so it stops short of a 5.
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 clear operational context: the default window is only orders updated in the last 24 hours, and since_last_updated is the escape hatch to look further back. That is actionable usage guidance, though it never says when to pick this tool over list_orders, list_printed_orders, or search_orders.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the account's user-defined order tags, optionally filtered by tag name. GET /api/tags.
| Name | Required | Description | Default |
|---|---|---|---|
| filter | No | Tag-name filter. | |
| page_size | No | Tags per page, 1-250 (default 50). | |
| page_number | No | Page number, from 1 (default 1). Pass the previous reply's next_page. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds that tags are account-scoped and user-defined, and names the HTTP method, but says nothing about pagination limits or what the result set looks like.
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 short sentences, zero filler, with the resource and its scope front-loaded before the optional filter and endpoint.
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-required-parameter read-only list tool with fully documented schema and annotation-covered safety, the description is nearly sufficient; it could briefly note the paginated return shape since no output schema exists, but an agent has enough to call 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?
Schema description coverage is 100%: filter, page_size and page_number are each documented in the schema, including the next_page chaining hint. The description's mention of tag-name filtering mirrors the schema rather than adding format or syntax 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+resource ('List ... order tags') and scopes it to the account's user-defined tags, which cleanly separates it from the mutation sibling starshipit_add_order_tags. The endpoint reference (GET /api/tags) reinforces the read-only retrieval intent.
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?
'optionally filtered by tag name' implies the primary use case, so usage is inferable, but there is no explicit statement of when to prefer this over e.g. search_orders or the order-listing siblings, and no exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List unshipped (new, not yet printed) orders with full details: addresses, items, packages, carrier. By default only orders updated in the last 24 hours; use since_order_date / since_last_updated to look further back. ids_only=true returns just the order ids. GET /api/orders/unshipped.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number, from 1 (default 1). Pass the previous reply's next_page. | |
| limit | No | Results per page, 1-250 (default 50). | |
| ids_only | No | Return only the unshipped order ids. | |
| since_order_date | No | Only orders created after this UTC date-time (RFC 3339). | |
| since_last_updated | No | Only orders updated after this UTC date-time (RFC 3339). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/openWorld/non-destructive, and the description adds real value on top: the hidden default-time-window behavior (last 24 hours) and the ids_only compact mode. It does not discuss pagination behavior or rate limits, but with annotations covering the safety profile this is solid.
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 tight sentences, front-loaded with the scope and contents of the result, followed by the default window and the ids_only variant. No filler; every clause carries 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?
With no output schema, the description carries the return-value burden and does so: full details plus the specific fields (addresses, items, packages, carrier) and the ids-only alternative. Nothing an agent needs to invoke it 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 baseline is 3, but the description adds meaning beyond the schema by explaining the default 24-hour window and framing the two date parameters as the way to look further back. That connects the parameters to a behavior the schema alone does not express.
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 ('List unshipped orders') and immediately defines the scope ('new, not yet printed'), which cleanly separates it from siblings like list_printed_orders, list_shipped_orders, and list_orders. An agent can pick this tool without opening any 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 concrete operational guidance: default lookback is 24 hours, and since_order_date / since_last_updated extend the window. It does not explicitly name which sibling to use for other order states, but the scoping definition implies the boundary well enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
A compact list of orders in one status (new, printed, shipped, archived) with contact, country, carrier, weight, manifest and dates, plus account-wide counts (unprinted, printed, shipped, archived, invalid addresses, returns). Supports filters and sorting. GET /api/orders/summary.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number, from 1 (default 1). Pass the previous reply's next_page. | |
| sort | No | Column to sort by. | |
| filter | No | Filter string COLUMN:::VALUE, several separated by commas, e.g. `Order:::1419,State:::NSW` or `Source:::Shopify`. Columns: Order, Name, Address (valid), Date (>=MAY 2024), Source, State, Country, Carrier, Service, Status, SKU, SingleSKU, Writeback, Weight (>=5), ShippingMethod, ShippingDescription, Tag. Prefix a column with ! to negate (!Country:::Australia). | |
| page_size | No | Results per page, 1-500 (default 50). | |
| order_status | Yes | Which orders to summarize. | |
| sort_direction | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. With no output schema, the description usefully enumerates the returned columns (contact, country, carrier, weight, manifest, dates) and the aggregate counts, but adds no auth, pagination or rate-limit 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?
Two sentences with no filler, and the scoping constraint plus return contents are front-loaded. The first sentence is dense to the point of being a run-on, which slightly hurts scanability.
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 read-only listing tool with annotations covering safety and no output schema, the description supplies the returned fields and the aggregate counts, which is what an agent needs. Filtering, sorting and pagination are covered by the schema, leaving little gap.
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 83% and the filter/sort parameters are thoroughly documented in the schema itself, so the schema carries the load. The description reinforces that filtering and sorting are supported and lists the four statuses, but adds no syntax or format detail beyond the schema.
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 action and resource — a compact order list scoped to one status plus account-wide counts — and front-loads its distinguishing feature (compact + aggregate counts) versus the plain list siblings. It never names the sibling it should be chosen over, so it stops short of full differentiation.
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?
Only 'Supports filters and sorting' is offered; there is no when-to-use versus starshipit_list_orders, starshipit_search_orders, or the per-status list tools, and no when-not conditions. Usage is implied by the word 'summary' at best.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search orders by order number, tracking number, customer reference or recipient name (phrase), optionally limited to unshipped or shipped orders. Returns id, number, date, name, carrier, tracking number and country. GET /api/orders/search.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number, from 1 (default 1). Pass the previous reply's next_page. | |
| limit | No | Results per page, 1-250 (default 50). | |
| fields | No | Which field to search (default All: order number, tracking number, reference, name). | |
| phrase | Yes | Search text, e.g. a name, order number or tracking number. | |
| status | No | Limit to unshipped or shipped orders (default All). | |
| include_child_accounts | No | Also search child accounts. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds genuinely useful detail by enumerating the returned fields (id, number, date, name, carrier, tracking number, country), which matters since there is no output schema. It says nothing about matching behavior (exact vs substring vs fuzzy on 'phrase'), which is a meaningful gap for a search tool.
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 plus the endpoint path, with the query capability front-loaded before the return shape. No filler and nothing redundant with the name.
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?
Because no output schema exists, the enumerated return fields are essential and present. Search semantics (matching mode) and any distinction from the list_* siblings remain unspecified, but for a read-only search endpoint whose annotations carry the safety profile, the description is nearly 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 all six parameters including enums and pagination are fully documented in the schema. The description only restates the search-field and status concepts already present there, adding no syntax, format or defaulting detail. 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 (search) and resource (orders) and enumerates the searchable fields plus the optional status restriction. However, it never distinguishes itself from siblings like starshipit_list_orders, starshipit_list_unshipped_orders or starshipit_list_shipped_orders, which overlap heavily with the status filter described here.
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?
No explicit when-to-use or when-not-to-use guidance is given, and no sibling is named. The agent must infer that a free-text phrase is the trigger for this tool rather than one of the several list_* order tools, even though 'optionally limited to unshipped or shipped orders' makes it a functional duplicate of two siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tracking details for a shipped order, by tracking number or by order number: status, carrier, tracking URL, shipment date and the carrier's tracking events. GET /api/track.
| Name | Required | Description | Default |
|---|---|---|---|
| order_number | No | Order number from the source platform. | |
| tracking_number | No | Carrier tracking number. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds the return payload (status, carrier, tracking URL, shipment date, events) and the GET endpoint, but says nothing about auth, rate limits, or failure when an identifier is unknown.
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?
One front-loaded sentence naming the keys, the returned fields then the endpoint. Minimal waste, though the trailing 'GET /api/track' adds little for an agent that only sees the tool interface.
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 enumerates the return fields, and it covers both lookup paths. Adequate for a simple two-parameter read tool, with only the missing sibling routing as a gap.
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: the lookup can be done by tracking number OR order number, which is not obvious from a schema where both parameters are optional with no required field.
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 (track) and resource (shipment) plus the two lookup keys, and lists the returned fields. It is clearly distinguishable from get_order or list_shipped_orders, though it never names a sibling to route against.
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?
No when-to-use guidance and no differentiation from the many order-related siblings (get_order, list_shipped_orders, search_orders). The use case is only implied by the phrase 'for a shipped order'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
WRITE: change details of ONE UNSHIPPED order by order_id (the order is read first and refused if it is already printed or shipped): addresses, shipping method/carrier/service, items, packages, reference or an internal note. This tool never sends status or manifest flags. It does not print a label or buy postage. Items/packages: include item_id / package_id (from starshipit_get_order with include=Items,Packages) to modify an existing line; a line without an id may be added. Nothing is deleted. Send only the fields you want to change. PUT /api/orders.
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | Internal order note. | |
| items | No | ||
| carrier | No | Starshipit carrier code, e.g. AusPost. | |
| currency | No | ||
| order_id | Yes | Starshipit order id. | |
| packages | No | ||
| reference | No | ||
| destination | No | ||
| order_number | No | ||
| sender_details | No | ||
| shipping_method | No | ||
| signature_required | No | ||
| carrier_service_code | No | ||
| shipping_description | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With destructiveHint=true already declared, the description adds the meaningful nuance that updates are partial and additive ('Nothing is deleted', 'Send only the fields you want to change'), plus a read-before-write validation step and the underlying PUT /api/orders. It does not describe the response body or error payloads, and 'nothing is deleted' sits in mild tension with the destructive hint, though modification of existing lines justifies it.
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-loaded with the operation and its guard condition, then the write semantics, then the nested-array rule. Dense but nearly every clause carries information; the long parenthetical and the 'PUT /api/orders' tail add a little clutter without much payload 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 14-parameter, nested-object mutation with no output schema and thin schema documentation, the description supplies the semantics that matter most: partial update behavior, no-deletion guarantee, id-based line editing, and refusal on shipped/printed orders. Remaining gaps are in the less ambiguous scalar fields, which an agent can reasonably infer from their names.
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 21%, so the description must compensate and largely does: it groups the mutable fields and, critically for the nested arrays, explains that including item_id/package_id modifies an existing line while an id-less line is added. Left unexplained are several top-level fields (currency, signature_required, order_number, shipping_description), so it is helpful but not exhaustive.
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 opening clause gives a specific verb, resource, and scope: 'change details of ONE UNSHIPPED order by order_id.' It then enumerates the mutable field families (addresses, shipping method/carrier/service, items, packages, reference, note), so an agent can distinguish it from create_order and the various list_* siblings 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?
Explicit preconditions ('refused if it is already printed or shipped') and explicit exclusions ('never sends status or manifest flags... does not print a label or buy postage') route the agent away from print/label/manifest tools. It also tells the agent to send only changed fields and where to obtain item_id/package_id (starshipit_get_order with include=Items,Packages).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read Shipday orders, carriers and delivery status; create orders and assign drivers.
Read orders, shipments and tracking events; create orders and rate quotes in Webshipper.
Get Shippit quotes, track and manage orders; create, label, book and cancel shipments on approval.
Read Track-POD orders, routes, drivers, vehicles and proof of delivery; create orders.
Add one secure layer between your agents and this server.