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

Beyond the write-oriented annotations, the description discloses the created-object result with its assigned `id`, validation failures, possible duplicate-code conflicts, and authentication errors. These details clarify persistence, failure modes, and the potential non-idempotent behavior without contradicting any annotation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose and usage guidance are front-loaded, and the headings make the material easy to scan. However, the exhaustive field inventory and large example substantially repeat a fully documented schema, making the definition longer than necessary.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The definition supplies the information needed to select and invoke the tool: creation scope, reuse scenario, required inputs, a complete nested request example, related retrieval tooling, and likely errors. The existing output schema and annotations further reduce the chance of important operational context being 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%, and the required/optional field lists largely repeat information already present in that schema. The concrete nested JSON example helps with payload assembly, but the description adds little new parameter meaning, validation guidance, or default behavior 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 opening sentence uses a specific verb and resource: adding a new entry to the StarShipIt address book for reuse in future orders. It also distinguishes the tool's role from `starshipit_list_addresses`, which is identified as the way to retrieve saved addresses.

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 explicit "When to use" section gives concrete situations involving frequent suppliers, warehouses, and customers, and explains the downstream retrieval workflow. It does not provide a when-not-to-use case, such as directing agents to `starshipit_update_address` when modifying an existing entry.

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

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

Beyond the annotations (which only declare non-readonly, non-destructive, non-idempotent, open-world), the description discloses the SKU uniqueness constraint, the 400 and 409 error semantics for duplicate or invalid input, and the downstream consequence that the product becomes matchable by SKU on order import. The 409-on-duplicate behaviour is consistent with idempotentHint=false.

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?

Structure is good and front-loaded, with bolded sections for required fields, optional fields, returns, and errors. However, the long optional-field enumeration duplicates a fully documented nested schema and does not earn its length; trimming it to the non-obvious constraints (units, uniqueness, customs-relevant fields) would improve the signal-to-noise ratio.

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-object mutation tool, the description covers required vs optional fields, units, uniqueness rules, error codes, and the downstream effect on order import, and an output schema exists so return values need not be detailed. Nothing an agent needs in order to call 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 description coverage is 100%, so the schema already documents every field including units (kg, metres), ISO country codes, and the HS code example. The description's bulleted field list largely restates that, adding only the 'must be unique across the catalogue' constraint for sku, which the schema already implies.

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 ('Add a new product to the StarShipIt product catalogue') and immediately explains the downstream role of catalogue products in order line-item auto-population. An agent can distinguish this from starshipit_update_product or starshipit_list_products 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 'Use this tool when' section gives two concrete scenarios: adding SKUs before order import, and seeding customs data for international shipments. There is no explicit exclusion naming the alternative (e.g. use starshipit_update_product for existing SKUs), so it stops short of full when/when-not routing.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=true, so the safety profile is partly covered. The description goes beyond them by disclosing the concrete effect (hidden from the fulfilment queue, record retained), reversibility (restorable at any time), and error semantics (404 not found, 401 invalid keys). It does not mention permissions or rate limits, so it falls short of fully exhaustive disclosure.

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 core definition, then cleanly sectioned into When to use / Parameters / Returns / Errors. The Parameters and Returns sections are somewhat redundant for a one-parameter tool with an existing output schema, but nothing is confusing or bloated.

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 mutation with full annotation coverage and an output schema, the description supplies everything an agent needs: effect, reversibility, selection guidance against delete, and failure modes. No material gap remains.

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 the single parameter is fully typed (positive integer, internal order ID), so the schema already carries the semantics. The description restates the parameter definition verbatim without adding format examples, ID-source hints, or constraints beyond what the schema provides; 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 ('Archive an order in StarShipIt') and immediately defines what archiving means: hidden from the main fulfilment queue but retained in the system. It is clearly separable from starshipit_delete_order, starshipit_update_order and starshipit_restore_order in the sibling list.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says to use this 'instead of deleting when you want to remove an order from the active queue while retaining its record', naming both the alternative action and the deciding condition. It also flags that archived orders can be restored, which routes the agent toward the restore path if needed.

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

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

Annotations already declare non-read-only, non-destructive, non-idempotent, open-world behavior, and the description adds genuinely useful context beyond that: it requires valid API keys for both source and destination accounts, returns a count of reassigned orders, and enumerates 400/401/403/404 failure modes. It does not address the non-idempotent nature (re-running with a stale current_api_key will fail) or whether partial batch success is possible, which are the remaining behavioral gaps.

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 purpose, then usage, then parameters, then returns and errors — a clean, scannable structure. The parameter section largely duplicates the JSON schema, which is the one place words could be trimmed, but nothing is confusing or 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 single-parameter, nested-instruction mutation tool this covers everything an agent needs: intent, when to use it, required inputs, a return-value summary (even though an output schema exists), and the full error taxonomy. Nothing material is left for the agent 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 description coverage is 100%, so both the top-level array and each nested field are already documented in the schema with the same wording. The description's parameter block restates order_id, current_api_key, and new_api_key without adding meaning such as how to obtain a source account's key or the batch-atomicity semantics.

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 — 'Reassign orders between StarShipIt accounts using API keys' — and immediately scopes it to 'move orders from one StarShipIt sub-account or warehouse account to another.' No sibling tool performs reassignment, so the agent can distinguish this from update/merge/clone tools 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 'When to use' block gives a concrete scenario (multi-account or multi-warehouse setups, routing orders after initial import), which is exactly the context an agent needs to select this over update_order or merge_orders. It does not name an explicit alternative or a when-not condition, which keeps it below a 5.

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

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

Annotations already cover the safety profile (mutating, idempotent, non-destructive, open-world), so the description's job is to add context — and it does: it states the cross-field requirement that at least one of `product_code` or `carrier_id` must accompany `order_ids`, describes the return shape (count of updated orders), and enumerates 400/404/401 failure conditions. It does not say whether partially-matching order sets are all-or-nothing on the 404 case, which is the main remaining gap.

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-loading the one-line summary before the labelled blocks is good structure, and the parameter, return and error sections are easy to scan. There is minor redundancy, since the 'When to use' paragraph re-explains what the opening sentence already said, but nothing is padded for its own sake.

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?

An output schema exists and the description still names what comes back (update count), and combined with the documented error codes, the inter-parameter constraint, and the required/optional split, an agent has everything needed to construct a correct call or interpret a failure. Nothing material is left unstated for a 3-parameter batch mutation.

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 descriptions of `order_ids`, `carrier_id` and `product_code` are largely a restatement of structured data, which sets the baseline at 3. The one genuine addition is the constraint that at least one of `product_code` or `carrier_id` should be supplied — a rule the schema does not encode — plus a concrete example value, but this is a modest increment.

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 sentence states a specific verb and resource — applying one carrier/service product across a batch of orders — which an agent can match to the task immediately. It does not, however, differentiate itself from the very similar sibling `starshipit_update_orders_bulk` or `starshipit_update_order`, leaving an ambiguity an agent must resolve on its own.

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 'When to use' block gives concrete triggering scenarios (carrier rate change, bulk service-level selection in a fulfilment workflow), which is clear positive guidance. It stops short of naming when NOT to use it or pointing at the bulk/individual update siblings as alternatives, so routing between them is left inferred.

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

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

Beyond the annotations, the description discloses the post-conditions (new order created in pending/unshipped state, label not printed), the side effect of address swapping in return mode, and concrete failure modes (400 invalid ID, 404 missing source, 409 non-cloneable state). These details are consistent with readOnlyHint=false and idempotentHint=false, since each invocation produces a new order.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The definition is front-loaded with purpose, then use cases, parameters, returns, and errors in a scannable structure. The inline JSON success example is somewhat redundant given an output schema exists, costing a little length without adding 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 two-parameter mutation tool, the description covers purpose, prerequisites, resulting state, and error handling, which is sufficient to call it correctly. It does not say which order fields carry over or whether the clone can be edited before labeling, but these are refinements rather than blockers.

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% and both parameters are already documented in the schema, including the origin/destination swap for to_return_shipment. The description largely restates this, adding only the framing that order_id refers to the 'source shipment' and that false means a standard clone — marginal added meaning.

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 first sentence names a specific verb and resource ('Clone an existing shipment in StarShipIt') plus the optional mode (return shipment). The 'When to use' paragraph clarifies that this duplicates an existing order rather than creating one from scratch, which separates it from siblings such as starshipit_create_order and starshipit_replace_shipment.

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 'When to use' section gives two concrete scenarios (resending the same goods, producing a prepaid return label from an outbound order) and warns that the result lands in a pending/unshipped state requiring a separate label print. It stops short of naming the alternatives (e.g., create_order vs. replace_shipment) or stating when cloning would be the wrong choice.

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

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

Annotations already declare readOnly=false, openWorld=true, idempotent=false, destructive=false, so the safety profile is covered. The description adds real value beyond them: the order lands in the unshipped queue, order_number must be unique, and specific failure modes (400 invalid, 409 duplicate, 401 bad keys) are spelled out — the 409 effectively warns that a retry of a non-idempotent call will fail rather than duplicate. It does not state permissions/scopes or rate limits, which is the remaining gap.

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 purpose, then when-to-use, then a scannable parameter list, then returns and errors — the structure is easy for an agent to parse. Some of the parameter bullets duplicate schema text and could be trimmed, but no sentence is actively misleading or wasted.

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 create tool with a single top-level object containing deep nesting, the description covers the side effect, the required-vs-optional split, the return value (assigned order_id), and the error contract. With an output schema present and 100% schema coverage, there is nothing material an agent needs to call this correctly that 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% and the nested order/destination/items/packages fields are all documented in the schema, so the baseline is 3. The description's parameter list largely restates what the schema already declares (required fields, ISO timestamp, item/package arrays); its only additive notes are the uniqueness constraint on order_number and the 'Express' example for shipping_method.

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 a new order in StarShipIt') and adds the downstream consequence ('will appear in the unshipped queue ready for label generation'), which tells an agent what happens next. It does not explicitly distinguish itself from the sibling starshipit_create_orders_bulk or starshipit_create_tracking_order, so an agent must infer the singular-vs-bulk split from the name.

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 'When to use' block gives a clear triggering condition: a new order has been placed and needs importing for fulfilment. It stops short of exclusions — nothing says to prefer starshipit_create_orders_bulk for multiple orders, or starshipit_create_tracking_order when only tracking data exists — so the boundary with those siblings is left to inference.

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

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

Annotations only declare the generic profile (write, non-idempotent, non-destructive, open-world); the description adds substantial context beyond that: per-order failure reporting in the response, 400/409/401 semantics, and low-level validation. The one gap is atomicity — it is not fully clear whether a duplicate order number (409) rejects the whole batch or just that entry, which matters greatly for a batch import.

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 purpose sentence, then labelled When to use / Parameters / Returns / Errors sections. Every line carries operational value and there is no filler or repetition of the schema field-by-field.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given an output schema exists, the description needn't detail return values, and it wisely only summarises 'summary of created orders plus per-order failures'. Errors and the batch-vs-loop tradeoff are covered. The remaining hole is partial-failure/rollback behavior for a mixed batch, which is the one thing an agent handling a large import would want stated.

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 nested order shape, required fields and item/package structure are already documented. The description adds a useful cross-reference ('same shape as starshipit_create_order') and restates the required order_number/destination, but nothing about the array constraints or per-item semantics beyond the schema. 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 ('Import multiple orders into StarShipIt in a single API call') and immediately scopes it as batch fulfilment import. The existence of the singular sibling and the framing make the bulk scope unambiguous 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?

Explicitly names the alternative ('Use instead of calling starshipit_create_order in a loop') and the condition that selects this tool (many orders at once, rate-limit efficiency). This is exactly the when-to-use/when-not guidance an agent needs to route between the two create tools.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=false, openWorldHint=true), the description adds real behavioral detail: partial-failure semantics (failed entries carry an `error` field rather than failing the whole batch), 400 for missing carrier/tracking_number, and 409 for duplicate tracking numbers. That duplicate-tracking error also makes the non-idempotent hint concrete.

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?

Heading-based structure is front-loaded and easy to scan, but the "Parameters" section reproduces the schema verbatim and the full example success response is redundant given the tool has an output schema. Roughly a third of the text earns no new 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 batch-creation tool, nothing an agent needs is missing: scope, entry requirements, per-entry failure handling, error codes, and return shape are all covered, and the output schema plus example remove remaining ambiguity.

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; the description adds the cross-field identifiability rule (at least one of `name` or `order_number` per entry, repeated twice as a hard note) and concrete carrier/tracking examples. It largely restates the schema's own per-field descriptions, so the gain over structured data is modest rather than substantial.

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 tracking-only orders") and immediately bounds the scope to "shipments dispatched outside the platform", which distinguishes it from the sibling create_order / create_orders_bulk tools that create fulfillment orders. An agent can classify the tool 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?

The explicit "When to use" block gives a clear entry condition: shipments booked or dispatched directly through a carrier, not via StarShipIt, that need centralised tracking. It stops short of naming the sibling alternative (create_order) to route away from, so the exclusion is implied rather than explicit.

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

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

Beyond the destructive and non-read-only annotations, it discloses irreversibility, possible partial success when some IDs do not exist, and representative 400 and 401/403 errors. These details materially affect how an agent should verify inputs and interpret the result.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the operation and irreversibility, then organizes usage, parameters, results, errors, and an example clearly. However, the permanent-deletion warning and the instruction to verify IDs with `starshipit_list_addresses` are each repeated, making it somewhat longer than necessary for a one-parameter 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?

For a simple but destructive operation, it supplies everything needed for safe selection and invocation: ID-based scope, batching, verification steps, error cases, and an important partial-success caveat. The output schema already exists, while the brief return description still clarifies the practical success semantics.

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

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

The schema already fully documents `address_ids`, including its integer items and non-empty constraint, so much of the parameter section repeats structured information. The concrete two-ID example and guidance to obtain and confirm IDs through the listing tool add useful practical context.

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 sentence gives a specific verb, resource, scope, and selection mechanism: deleting one or more StarShipIt address-book entries by ID. This clearly distinguishes it from siblings that delete orders or products and from address listing or updating tools.

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 explicitly recommends the tool for outdated, duplicate, or unwanted entries and notes that multiple IDs can be deleted in one call. It also gives a concrete pre-deletion workflow using `starshipit_list_addresses` with a search term to verify the intended IDs.

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

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

Annotations already flag destructiveHint/idempotentHint, but the description goes well beyond them by disclosing irreversibility, that the order is removed entirely, and specific error semantics (404 not found, 409 shipped, 401 auth) that tell the agent exactly how failure modes map to preconditions.

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 core action and clearly sectioned with headers for when-to-use, parameters, returns, and errors, though the irreversibility warning is stated twice (opening line and Warning block), a minor 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 one-parameter destructive tool this covers everything an agent needs: scope, alternative routing, return confirmation, and error-condition behavior, with an output schema already handling return structure.

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 the single parameter's schema text is verbatim identical to the description's parameter note, so the description adds no meaning beyond the schema; 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 ('Permanently delete an order from StarShipIt') and immediately clarifies the permanence, which distinguishes it from the sibling archive/restore tools.

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 when-to-use condition ('Only use on unshipped orders created in error') and routes the agent to the named alternative `starshipit_archive_order` for retain-but-hide cases, plus documents 409 for shipped orders as a further exclusion.

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

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

Although annotations already mark this as destructive, non-read-only, idempotent, and open-world, the description adds important behavioral context: the operation is irreversible, deleting all products has no undo, and partial deletes may still succeed when some IDs are not found. It also documents per-product errors, which materially helps an agent reason about outcomes.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well structured and front-loads the irreversible nature of the operation, followed by mode guidance, parameters, returns, errors, and use cases. It is appropriately thorough for a destructive tool, though some parameter and return details repeat information already present in the schema and 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?

Given the destructive nature of the tool, the description is complete enough for correct invocation: it covers both modes, required empty-array behavior, irreversibility, partial-failure behavior, error cases, and when to use it. Output schema exists, so the brief returns section is supplemental rather than necessary.

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 already 100%, so the baseline is 3. The description adds useful meaning beyond the schema by explaining the coupling between product_ids and all_products, including that an empty product_ids array is only valid when all_products is true and that product_ids is ignored when all_products is true.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: deleting one or more products from the StarShipIt product catalogue. It clearly distinguishes the two supported deletion modes, specific product IDs versus deleting the entire catalogue, so an agent can understand the operation 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?

The description includes an explicit 'Use this tool when' section with concrete scenarios such as removing discontinued products or purging test products. It also gives clear mode-selection guidance: specific product IDs are recommended, while all_products=true is framed as an extreme-caution path with no undo.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantive context beyond them: caching behavior and how to bypass it, plus concrete error semantics (400 for missing/invalid data, 404 for unknown order_id, 401/403 auth). The response field list also flags that pricing_breakdown is embedded JSON, which is non-obvious behavior.

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 purpose, then gated by bolded headers, and the two runnable examples are high value. Minor waste: the Parameters section largely restates what the 100%-covered schema already documents, which lengthens an otherwise tight definition.

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 6-parameter tool with nested addresses and packages and a 0-required-parameter shape, the description covers the mutually exclusive input modes, the caching flag, error outcomes, and worked examples for both modes. With an output schema present, the return-value sketch is surplus but harmless.

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; the description earns above that by stating the conditional dependency (sender/destination/packages required only when order_id is omitted) and by explaining that refresh_rate forces a live carrier lookup rather than cached data. It does not mention response_format at all, leaving that enum entirely 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?

States a specific verb and resource ("Get available delivery services (carrier + service options)") plus the scope (for an order or a general route) and what the return values are good for ("service codes directly usable when creating or updating orders"). It explicitly names the sibling tool it supersedes, so the agent can discriminate without opening schemas.

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?

A dedicated "When to use" block gives three concrete selection conditions and names the alternative (starshipit_get_rates) it should be preferred over, plus the refresh_rate escape hatch for fresh lookups. The order_id vs sender/destination/packages switch is stated as an explicit rule rather than left to inference.

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

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

Adds real behavior beyond the annotations: JSON text output is capped at 25000 characters while full base64 always lives in structuredContent, markdown mode lists only file names and sizes, plus documented 404/401/403 error cases. That truncation disclosure is exactly the kind of gotcha an agent needs. The one flaw is the inconsistent claim about 'retrieving document URLs' when the tool returns base64 content, which muddies the behavioral picture.

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 core action, then cleanly sectioned into parameters, returns, errors, and use cases. Slightly verbose and it repeats pagination defaults already in the schema, and the 'document URLs' line is both inaccurate and unnecessary.

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 filtered-list tool with an output schema and full annotation coverage, the description supplies everything missing: response shape, format-dependent truncation, error semantics, and selection criteria. Nothing an agent needs to invoke it correctly is absent.

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 baseline would be 3, but the description adds meaning for response_format by explaining what markdown vs JSON actually produce and where the full payload lives. It also restates the manifest_id omit-to-list-all semantics and limit/page defaults, which is duplicative but harmless.

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: 'Retrieve manifest documents (PDF, XML, etc.) as base64 file content.' An agent can distinguish this from starshipit_list_manifests, but the description never names or contrasts that sibling explicitly, so differentiation is inferred rather than stated.

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?

A dedicated 'Use this tool when' block gives three concrete triggering scenarios (handing a PDF to a carrier driver, pulling docs for a manifest ID, listing all docs). No when-not-to-use guidance or named alternative (e.g., list_manifests) is provided, so it stops short of full routing clarity.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered. The description adds genuinely new behavior: the 400 error when neither identifier is supplied, 404 on not-found, and 401 on invalid keys — plus what the returned payload contains. Return-shape detail is somewhat redundant given an output schema exists.

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?

Headers and front-loaded purpose make it scannable, but the 'at least one identifier' rule is repeated three times (intro, Parameters, Errors), and the full example JSON response duplicates information already available in the output schema. The content is useful but noticeably padded for a three-parameter read 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?

With annotations and an output schema available, the bar is mostly about invocation correctness: the identifier constraint and error cases are documented, so an agent can call it successfully. The only real gap is that `response_format` and its enum are left to the schema alone.

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 per-parameter text largely restates the schema. However, the description contributes the cross-field constraint that at least one of `order_id` or `order_number` must be supplied, which is absent from the schema (no required list, no anyOf), and clarifies the merchant reference format. The third parameter, `response_format`, is never mentioned.

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 ('Retrieve a single order') plus the two lookup keys, and the word 'single' implicitly separates it from the many list_*/search_orders siblings. An agent can identify the right tool 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?

The 'When to use' block gives a clear condition: when full detail of one specific order is needed (destination, items, packages, carrier, metadata). It does not explicitly name the alternative to pick instead when searching by other criteria (e.g. starshipit_search_orders), so it falls short of a 5.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered; the description adds value by disclosing pagination defaults, the max-250 cap, the has_more flag, and concrete error semantics (400 on unrecognised status, 401 on bad API keys). The only real omission is what 'summary' contains beyond a list plus has_more, which the output schema likely covers.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose and 'when to use' are front-loaded, and the headers make it skimmable. The Parameters section duplicates schema content almost one-for-one, which is mild waste given the schema coverage, but the Returns and Errors blocks each earn their space.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only listing tool with full annotation coverage, a complete schema, and an output schema, the description supplies everything an agent needs to invoke it correctly: filtering, sorting caveat, pagination bounds, output format, and failure modes. Nothing material 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 every parameter is already documented, and the description's parameter block largely restates the schema (defaults, max, enum values). It does add example status values and clarifies response_format's intent ('markdown' human-readable vs 'json' machine-readable), but 'refer to the StarShipIt API docs' leaves the sort field as opaque as the schema does — no net gain there.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('Get a summary of orders filtered by status from StarShipIt') and scopes it to reporting/dashboard use. It never names the overlapping status-specific siblings (starshipit_list_shipped_orders, starshipit_list_delivered_orders, starshipit_search_orders), so an agent still has to guess whether this or a dedicated list tool is the right call.

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 'When to use' line gives an explicit positive condition ('status-specific count or listing for reporting') and an exclusion ('not fulfilment operations'), which meaningfully trims the candidate set. It stops short of pointing at the specific alternative tools to use instead for fulfilment or free-text lookup.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, open-world), so the bar is lower; the description still adds value by documenting 400/401/403 causes and the empty-result case where no connected carrier supports the lane. It could say more about pricing currency/surcharge behavior, but the error and no-rates semantics are genuinely useful additions.

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 one-line purpose followed by clearly labeled When to use / Required parameters / Returns / Errors sections, plus a concrete example body. It is somewhat longer than necessary because it repeats schema constraints (required address fields, kg/metres units) that the schema already enforces.

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 three-object payload with four parameters, the description supplies call timing, address shape, package geometry guidance, response fields (service_code vs service_name, total_price), failure modes, and a worked example. An agent could invoke this correctly without opening 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 coverage is 100%, so units (kg, metres) and field-level notes are already documented in structured form. The description mostly restates required fields and adds a mild hint that city/state improve accuracy, but never mentions the `response_format` parameter at all, so it does not exceed the baseline.

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 sentence gives a specific verb and resource: retrieve available shipping rates (quotes) for a shipment between sender and destination with given package dimensions. It is clearly distinguishable from siblings like starshipit_create_order (which consumes the rates) and starshipit_get_delivery_services (which lists services rather than prices).

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 states a concrete trigger — call before creating an order when comparing services by price — and that it is read-only and safe to repeat. It does not name a sibling alternative (e.g. when to prefer get_delivery_services or tracking lookups instead), so the when-not guidance is implicit rather than explicit.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is settled. Beyond that the description discloses the shape of the payload (groups with a suggested parent and child orders, a has_more flag) and the 401 auth failure mode, which are genuinely additive; it stops short of describing ordering or pagination edge behavior.

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 purpose and the next-step tool, then cleanly sectioned into when-to-use, parameters, returns and errors. The bold-labeled blocks and the parameter list largely duplicate schema and output-schema content, so a sentence or two could be trimmed without loss.

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 tool with a full schema and an output schema, the description supplies everything else an agent needs: what candidates mean, how to page, and which tool to call next. No material gap remains.

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 nuance: limit counts 'result groups per page' rather than individual orders, which is a semantic distinction the schema does not make. Defaults and the 250 cap are restated from the schema with no added value.

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 ('Get a list of orders that StarShipIt suggests can be merged') plus the heuristic behind the suggestion (same customer, same destination). It is clearly distinguished from the sibling starshipit_merge_orders, which performs the merge rather than the discovery.

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 'When to use' line gives the operational context (order processing, consolidation to cut shipping costs) and the description names the follow-up tool, starshipit_merge_orders, as the action to take on the results. When-to-use and the alternative/next step are both covered.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered; the description adds real value with pagination mechanics ('if total_records > limit × page, increment page') and the 401/403 and empty-result failure modes. It does not cover rate limits or result ordering, but for a read-only list that is a minor gap.

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?

Bold section headers make it easy to scan and the when-to-use guidance is front-loaded right after the purpose sentence. The 'Returns' block duplicates field information that the output schema already supplies, which is the main wasted space.

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 paginated read-only list tool, the description covers purpose, filtering, pagination math, and error cases, which is enough for an agent to call it correctly. Enumerating return fields is redundant given an output schema exists, and the unmentioned response_format parameter is the only real content 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 schema already documents all four parameters, including defaults and limits; the description largely restates them. It does add the useful semantics that search_term matches across name, company, street, suburb, city, and postcode and that a blank term lists everything, but it omits response_format entirely, so a baseline 3 is right.

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 first sentence names a specific verb and resource ('List saved addresses from the StarShipIt address book') and scopes it with filtering and pagination, which cleanly separates it from sibling mutations such as starshipit_add_address, starshipit_update_address, and starshipit_delete_addresses.

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 'When to use' block gives three concrete scenarios, including the ordering-relevant one of looking up a contact before creating an order. It stops short of naming an alternative tool or stating when not to use this one, so it falls just under a 5.

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

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

The annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is largely covered. The description adds useful context beyond the annotations by specifying that results are limited to carrier-confirmed deliveries, describing the returned Order objects, and noting a 401 error for invalid API keys. It does not discuss pagination or rate limits, which keeps it below 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?

The description is front-loaded with the core purpose, then organized into clear 'When to use,' 'Parameters,' 'Returns,' and 'Errors' sections. Every section contributes useful information, and there is no redundant or filler wording.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only list tool with two optional parameters, full schema description coverage, rich annotations, and an output schema, the description is complete. It covers purpose, usage context, parameter notes, return contents, and an error case, leaving no significant gap for an agent 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%, so the schema already fully documents order_ref and response_format, and the description largely repeats those definitions. It adds only marginal meaning by noting that order_ref is useful for looking up a specific customer's deliveries, which is helpful but not substantial enough to exceed the baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'List delivered orders from StarShipIt,' and narrows the scope to orders where the carrier has confirmed delivery. That scope distinguishes it from sibling status-list tools such as starshipit_list_shipped_orders and starshipit_list_unshipped_orders without requiring the schema to be opened.

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 'When to use' section gives clear contexts: post-delivery reporting, customer-service lookups, and reconciliation workflows. It does not name alternatives such as starshipit_search_orders or starshipit_list_shipped_orders, nor does it state when not to use this tool, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that with pagination mechanics (limit max 250, page) and documented 401/403 auth failures. The 'Returns' section largely restates what the output schema already declares, limiting the additional behavioral disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose statement is front-loaded and the bolded section headers (Returns, Pagination, Error cases, Use this tool when) make it easy to scan. It is somewhat longer than necessary because the return-field enumeration duplicates an existing output schema, but nothing is actively confusing.

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 list tool, the description covers selection criteria, pagination, auth error behavior, and return shape, which is close to complete. The only meaningful omission is guidance on when to prefer the carrier- or tracking-scoped manifest siblings over this general lister.

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, and response_format are already documented, making 3 the baseline. The description's pagination note repeats the limit ceiling already present in the schema and says nothing about response_format, so it adds little semantic meaning 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 opens with a specific verb+resource ("List all manifests in your StarShipIt account") and defines what a manifest is, which is genuinely useful domain context. It stops short of explicitly differentiating itself from close siblings like starshipit_manifest_by_carrier or starshipit_manifest_by_tracking, so an agent still has to infer which lister to pick.

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?

A dedicated 'Use this tool when' block gives three concrete scenarios (review past manifests, look up an ID before PDF download, audit submitted shipments), which gives clear positive-selection context and even implies a follow-up call to get_manifest_files. There are no explicit exclusions or named alternatives, so it stops one step short of a 5.

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

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

Beyond the read-only and idempotent annotations, it explains the operational shipment state, discloses 401 errors for invalid API keys and 400 errors for unrecognized statuses, and notes the has_more pagination indicator. These details provide useful invocation and result-handling context, though the behavioral disclosure is not unusually extensive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose and usage guidance are front-loaded, and the headings and bullets make the details easy to scan. The full parameter recapitulation and Returns section duplicate structured schema information, making the description longer than strictly necessary without creating confusion.

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 paginated list tool, it covers lifecycle scope, practical use cases, filtering, pagination, output formats, result contents, continuation signaling, and common errors. Together with the complete input schema, output schema, and safety annotations, this is enough for reliable selection and invocation.

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

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

Schema coverage is 100%, and much of the parameter section repeats defaults, limits, and formats already present there. It nevertheless adds useful meaning by explaining that recently_printed means labels were printed recently while unmanifested means printed but not yet manifested.

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 sentence clearly specifies the verb, resource, and lifecycle scope: listing StarShipIt orders whose labels have been generated. The printed/unmanifested distinction helps separate it conceptually from other order lists, but it does not explicitly differentiate or route away from siblings such as starshipit_list_unshipped_orders or starshipit_search_orders.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives concrete use cases: auditing recently printed shipments and finding orders awaiting manifesting before carrier pickup. It lacks explicit when-not-to-use guidance or named alternatives for other order states, so the guidance is clear but not exhaustive.

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

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

Annotations already declare readOnly, idempotent, non-destructive, open-world behavior, so the safety profile is settled. The description adds real value beyond that with error cases (401/403 credentials, 400 out-of-range page_size) and the empty-string-lists-all convention. It does not discuss result caps, rate limits, or what happens with very large page_size values, so it stays mid-range.

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 and well-sectioned, but bloated: the parameter block duplicates schema descriptions, and the return value is presented twice (a long field list plus a JSON example) even though an output schema exists. Both of those sections could be removed without losing information the agent doesn't already have.

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 7-parameter read-only list tool, nothing essential is missing: identity of the resource, search semantics, the empty-string convention, pagination mechanics and the non-standard pagination warning, error conditions, and use cases are all present. Annotations carry the safety profile and the output schema carries the return shape, so the redundancy in the returns section is harmless rather than 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 description coverage is 100%, so baseline is 3. The parameter block largely restates the schema text verbatim (search_term, page_number, page_size, sort_column, sort_direction, skip_records). The one genuinely additive item is the note that this endpoint uses page_number/page_size/skip_records instead of the page/limit convention elsewhere, and that skip_records can be combined with page_size for offset paging — but response_format is never mentioned in the description at all.

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 first sentence states a specific verb and resource ('List or search products in the StarShipIt product catalogue') and the follow-up explains what a product is (pre-configured line-item template with customs data and dimensions). This clearly separates it from the mutate-oriented siblings add_product, update_product, and delete_products.

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 'Use this tool when' block gives three concrete scenarios (SKU lookup before order creation, customs auditing, dimension/weight checks), which is stronger than most list tools. What's missing is any explicit exclusion or named alternative (e.g. 'to create or modify products use add_product/update_product'), so it stops short of a 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds value beyond them by disclosing pagination via a has_more flag, per-page limits, and the 401 auth-failure condition, though it says nothing about ordering guarantees 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?

Front-loaded with purpose, then clearly sectioned headers for when-to-use, parameters, returns, and errors. The parameter bullets duplicate the schema descriptions, costing some words, but the structure makes scanning fast and nothing is truly extraneous.

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 paginated list tool with a full schema and an output schema, the description covers purpose, usage, pagination, and an error case, which is close to complete. Only minor gaps remain (result ordering, whether has_more requires requesting the next page).

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% and each property is described there, so the parameter section largely restates the schema (including the same ISO 8601 example). The one modest addition is grouping the params with defaults in one place, but it adds no meaning 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 verb and resource ('List shipped orders from StarShipIt') and clarifies the scope as orders 'manifested and dispatched to the carrier', which implicitly separates it from siblings like list_printed_orders and list_unshipped_orders. It does not explicitly name those siblings, so the differentiation is inferred rather than declared.

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 'When to use' section gives concrete contexts (checking dispatch history, feeding tracking workflows), which is clear usage guidance without naming exclusions or alternatives. An agent gets a positive signal but no explicit 'use X instead for Y' routing against the many sibling list/search tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the description's "read-only and safe to call multiple times" mostly restates them. It does add genuinely new behavioral context: pagination semantics via the has_more flag, default limit and max cap, and concrete failure modes (401 for missing/invalid API keys, 429 for rate limiting) that annotations cannot express.

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?

Headers are front-loaded and scannable, with purpose and when-to-use before details. There is some redundancy: the full parameter list restates a 100%-covered schema, and the JSON example response duplicates ground already covered by the existing output schema, so a few lines do not earn their 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 paginated read tool, the definition covers pagination, filtering, output format, and error codes, which is more than enough to invoke it confidently — and the output schema means return values need not be re-explained (making the JSON example optional rather than load-bearing). The only real gap is routing guidance among the many order-listing siblings.

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 every parameter is already documented in the schema, and the description's parameter block largely mirrors it. The one small addition is the worked ISO 8601 example, but the schema already carries an equivalent example string, so meaning added beyond structured data is minimal — 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 unshipped orders from StarShipIt") and immediately defines the resource boundary: "orders that have been imported but not yet shipped." That definition alone distinguishes it from siblings like starshipit_list_shipped_orders and starshipit_list_delivered_orders without needing to name them.

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 "When to use" block gives a clear trigger ("see your pending fulfilment queue") plus a safety/retry statement. It stops short of explicit exclusions or alternatives — it never says to use starshipit_search_orders when filtering by customer, or starshipit_list_shipped_orders for completed orders — so an agent must infer routing from the sibling names.

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

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

Goes well beyond the annotations by disclosing the mutation's reach ('closes every shipment that is ready-to-manifest' and creates a single manifest document) and enumerating error states 400/404/409, which matter for a tool with openWorldHint=true that submits to a real carrier. The idempotentHint=true is consistent with the 409 'may already be manifested' note.

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 core action and organized under bold headers, so it scans well. The 'Returns' section is partly redundant with the existing output schema, and the end-of-day guidance appears twice (prose and the 'Use this tool when' list).

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 bulk mutation with an output schema, the description covers when to use it, carrier value handling, side effects, and failure modes — everything an agent needs before invoking 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 coverage is 100%, so the baseline is 3; the description adds useful guidance beyond the schema by listing common carrier identifier strings and warning to check StarShipIt account carrier settings for the exact strings. It says nothing about response_format, which is left entirely 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?

States a specific verb and resource with explicit scope: 'Manifest ALL unmanifested shipments for a specific carrier in one operation.' The emphasis on ALL plus 'rather than selecting individually' implicitly distinguishes it from the per-shipment siblings (starshipit_manifest_by_tracking, starshipit_manifest_shipment).

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 context — 'at end-of-day or before carrier pickup' — plus a dedicated 'Use this tool when' list. It does not name the specific sibling to use instead when manifesting one shipment at a time, leaving that routing to the agent's inference.

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

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

Annotations only declare readOnly=false, idempotent=true and destructive=false; the description goes well beyond them by disclosing the irreversible consequence ('shipments are locked and can no longer be edited'), the manifest document side effect, and the 400/409/422 failure semantics. The already-manifested 409 case is consistent with the idempotent hint rather than contradicting 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-loads the one-line purpose before the bolded sections, and each block (parameters, returns, errors, when-to-use) is scannable. Minor redundancy: the parameter block largely duplicates the 100%-covered schema, which costs a little space without adding 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 state-changing, adjacent-to-destructive operation it covers the operation's effect, the irreversible post-state, return fields, and per-status error conditions — everything an agent needs before calling. The output schema exists, yet the returns summary is still a useful index of what comes back, not padding.

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 defines tracking_numbers, use_order_numbers and response_format. The description restates the two body parameters with essentially the same meaning (non-empty array, boolean switch to order numbers) and adds no syntax, format, or batching detail beyond what the schema provides.

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 ('Manifest (close/submit) specific shipments to the carrier by their tracking numbers or order numbers') and scopes it to a supplied list, which clearly separates it from starshipit_manifest_by_carrier and starshipit_manifest_shipment.

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?

Three explicit 'Use this tool when' bullets cover the positive cases, and the phrase 'subset of shipments rather than all shipments for a carrier' implicitly routes away from the carrier-wide sibling. It stops short of naming the alternative tool or stating exclusions (e.g. when to use manifest_shipment instead), so it is strong but not exhaustive.

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

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

Beyond annotations it discloses the key risk (manifesting cannot be easily reversed), the prerequisite that labels must already be printed, and concrete error semantics (400/404/409). The idempotency claim merely restates idempotentHint=true, and destructiveHint=false is not visually contradicted since manifesting locks state rather than deleting data.

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 action, then labelled When to use / Important / Parameters / Returns / Errors sections that are easy to scan. The inline example JSON response is partly redundant given an output schema exists, making it slightly longer than necessary.

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 one-parameter, state-committing tool the definition covers prerequisites, irreversibility, idempotency, return payload (base64 PDF plus label type), and the full set of failure codes. Nothing an agent needs before calling is missing.

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

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

Schema coverage is 100%, so the schema already documents order_ids, its integer item type, and the label prerequisite. The description repeats that content plus the word 'numeric' but adds no format, batching limit, or ordering semantics beyond the schema — 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?

"Manifest (finalise/close) shipments by order IDs" gives a specific verb, resource, and selection axis. The 'by order IDs' phrasing implicitly separates it from siblings like starshipit_manifest_by_tracking and starshipit_manifest_by_carrier, but neither is named, so an agent must infer the routing rule.

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 'When to use' section states the operational context clearly: end-of-day batch finalisation before carrier pickup, with a caution to verify labels first. It stops short of explicitly naming when to prefer the tracking- or carrier-based manifest siblings instead.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is known; the description still adds real value with the post-state ('child orders are absorbed', 'dispatched as a single package'), compatibility constraints (matching destination addresses) and specific error semantics (400/404/409/401). It slightly restates the destructive warning the annotation already carries.

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 purpose, then clearly sectioned into when-to-use, parameters, returns, warning, errors. Slightly heavier than needed for a two-parameter tool, with the parameters and returns sections duplicating structured data, but no section is wasted.

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 two-parameter merge, the agent gets trigger conditions, prerequisites, post-merge state, compatibility caveats, and failure modes; an output schema exists so the brief 'Returns' note is sufficient.

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% and both field descriptions already explain parent vs. children. The description's per-parameter bullets largely restate the schema, adding only the emphasis that the parent is 'kept as the merged result' and that at least one child is required (already enforced by minItems=1).

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?

Names a specific verb (merge) and resource (orders) with explicit scope: many-to-one children into a parent, resulting in one package. Easily distinguished from siblings like starshipit_update_order or starshipit_get_suggested_merges.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states the trigger condition ('customer has placed multiple orders that should ship together in one box') and names the alternative/recommended preceding step, starshipit_get_suggested_merges, to find candidates.

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

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

The annotations already declare this is a non-read-only, open-world, non-idempotent, non-destructive operation. The description adds useful behavioral context beyond those annotations: reprint defaults to false, a 409 occurs when a label already exists and reprint is not true, and the return includes label data plus tracking/carrier/service. It does not discuss permissions or rate limits, but the important operational behavior for this mutation 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?

The description is front-loaded and clearly organized with When to use, Parameters, Returns, and Error cases. It is somewhat longer than necessary because it repeats parameter details and includes a full success-response example even though an output schema exists, but the structure remains easy to scan.

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-order label-printing mutation with rich annotations and an output schema, the description supplies the use case, all parameter meanings, reprint semantics, return shape, and the key error cases including 400/404/409. An agent has enough information to call the tool correctly and interpret likely failures.

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 the input schema already documents all five parameters, including the package weight and dimension fields. The description restates those meanings and adds carrier/service examples, but it does not add substantial semantics beyond the schema, so the baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb and resource: print or reprint a shipping label for a single StarShipIt order. It explicitly distinguishes the single-order case from the bulk sibling `starshipit_print_labels`, so an agent can choose between them 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?

It states exactly when to use this tool and when to use an alternative: one specific order versus multiple orders, where the bulk tool is preferred. That covers both the primary use case and the routing condition to the sibling tool.

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

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

Beyond the annotations, the description discloses per-order failure isolation, the shape of returned label results, and concrete error cases including 409 when labels already exist without `reprint=true`. This adds meaningful behavioral context for a non-read-only, non-idempotent operation without contradicting the supplied hints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well organized with front-loaded when-to-use guidance, parameter notes, returns, and error cases. The example response is somewhat verbose relative to the schema and output schema, but the structure makes the important selection criteria easy to find.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of a bulk mutation tool, the description covers usage routing, parameter behavior, partial success semantics, return values, and error cases. Although an output schema exists, the extra return and error detail makes the tool sufficiently complete for an agent 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 already 100%, and the description mostly restates the parameter meanings. It does add some useful context around `reprint` via the 409 error case, but it does not substantially deepen parameter semantics beyond what the schema already documents.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('Print shipping labels') plus a clear bulk scope ('multiple orders at once'). It explicitly distinguishes itself from the sibling `starshipit_print_label`, so an agent can choose between single and bulk label printing 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?

It gives explicit when-to-use guidance: two or more orders in a single call. It also names the alternative for a single order and explains why that alternative is preferable (carrier override, package dimensions), leaving little to inference.

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

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

Beyond the annotations, it discloses the return shape (URL or base64 PDF), the aggregation behavior (multiple orders combined into a single PDF), a concrete success payload, and specific error codes (400 for missing/invalid IDs, 404 for nonexistent orders). The one undisclosed behavior is what readOnlyHint=false means here — whether generating slips records a print event or otherwise changes order state is never explained.

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?

It is front-loaded with the action, then cleanly sectioned into when-to-use, parameters, returns, and errors, so an agent can stop reading at any point with what it needs. The inline example response is slightly redundant with the output schema, but it is short and reinforces the PDF-URL pattern rather than padding the text.

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 generation tool with full schema coverage and an output schema, the definition covers purpose, triggering scenario, return format, and failure modes, which is everything needed to invoke it correctly. The only missing piece is the side effect implied by a non-read-only, non-idempotent annotation profile.

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 only one parameter, so the schema already carries the semantics; the baseline of 3 applies. The description restates that order_ids is required and must contain at least one ID, which the schema already enforces via required and minItems, adding no new meaning such as ID sourcing or practical batch-size limits.

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+resource: 'Generate packing slip documents for one or more orders in StarShipIt.' It implicitly separates itself from the label-printing siblings by stating packing slips don't require a label first, but it never names starshipit_print_label or starshipit_print_labels explicitly, so the sibling differentiation is inferred rather than stated.

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?

A dedicated 'When to use' block gives a concrete scenario (warehouse staff picking, packing, verifying order contents before shipment) and a useful prerequisite clarification (no label needed first). There is no when-not-to-use guidance and no explicit pointer to the label-printing alternative for the adjacent task, keeping it short of a 5.

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

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

Annotations already declare destructiveHint=true and non-idempotence, and the description adds substantive context beyond them: the carrier label is actually voided, the action is unrecoverable if dispatched, and specific error codes (400/404/409 manifested-or-dispatched) are enumerated. This is real behavioral disclosure, not restatement.

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?

Headings (When to use, Warning, Parameters, Returns, Error cases) make it well front-loaded and scannable. However, the full example success-response JSON is somewhat redundant given a dedicated output schema exists, making the definition longer than strictly necessary.

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 destructive tool, the description covers purpose, trigger conditions, hazard, parameters, and error behavior. The return-values section is arguably duplicative of the output schema, but nothing an agent needs in order to call 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?

There is a single parameter at 100% schema description coverage, and the description's explanation ('numeric StarShipIt order ID whose label should be voided and replaced') largely mirrors the schema's own description. It adds the 'numeric' type hint but no format or sourcing guidance 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?

First sentence states a specific verb and resource and adds the key mechanism ('voids the previous label and creates a new one'), which distinguishes it clearly from siblings like starshipit_clone_shipment or starshipit_manifest_shipment. An agent can identify the tool's distinct effect 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?

Explicit when-to-use is given ('when an existing label must be voided and replaced, such as address correction, weight change, carrier change') plus an explicit when-NOT-to-use warning for dispatched packages with guidance to coordinate with the carrier. This is the full when/when-not/alternative pattern done well.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description goes beyond that by disclosing the state effect (re-entering the fulfilment queue) and the failure semantics (404 when not archived, 401 on invalid keys), which is exactly the added context that matters for a mutating call.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the action in one sentence, then organizes the remainder into labelled When to use / Parameters / Returns / Errors blocks that are easy to scan. Slightly header-heavy for a one-parameter tool, but no sentence is wasted.

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 mutation with annotations and an output schema, the description supplies purpose, precondition, failure modes, and side effect. The 'Returns' line is mildly redundant with the output schema but not misleading, and nothing an agent needs to call 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 description coverage is 100% and the single parameter is already documented as 'StarShipIt internal order ID to restore from archive'. The description restates it verbatim rather than adding format or lookup guidance, so the schema does the heavy lifting and 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 (restore an archived order) and its outcome (returned to the active fulfilment queue). It is immediately distinguishable from siblings like starshipit_archive_order, starshipit_update_order, and 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?

The 'When to use' block explicitly names the inverse operation starshipit_archive_order and the condition that selects this tool. The error note ('404 if order not found or not currently archived') further delineates the precondition, leaving little to inference.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive, so the safety profile is covered; the description goes further by disclosing error codes (400 empty phrase, 401 bad keys, 429 rate limit) and pagination behavior via the has_more flag. The rate-limit and empty-input failure modes are exactly the kind of operational context an agent cannot get from annotations or schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose and then cleanly sectioned into When to use, Parameters, Returns, and Errors, which is easy to scan. The parameter list largely duplicates the schema and is the one section that does not fully earn its space, but overall there is little wasted prose.

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 four-parameter search tool with an output schema already defined, the description covers the missing pieces an agent needs: what is searched, partial matching, pagination signal, and failure modes. Nothing material for a correct invocation is left undisclosed.

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 four parameters are already documented with defaults, bounds, and an enum for response_format. The description's parameter block restates the same defaults and max 250 rather than adding new meaning such as matching semantics, phrase length behavior, or how limit interacts with has_more; 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?

The description names a specific verb and resource ("Search orders in StarShipIt") and immediately scopes the search to a free-text phrase across order numbers, references, recipient names, and tracking numbers. The line "Use when you need to find a specific order but don't have the exact order_id" implicitly separates it from get_order and the many list_* siblings, so an agent can route correctly 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?

There is an explicit "When to use" block with the selecting condition (no exact order_id) plus the note that partial matches are supported. It stops short of naming the alternative tools (e.g. starshipit_get_order for exact IDs, or the status-scoped list_* tools), so the agent must infer the exclusions rather than being told them.

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

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

Annotations already declare readOnly/idempotent/destructive/openWorld, so safety is covered; the description adds genuinely new behavior: 404 when the tracking number is not found and 400 on malformed numbers. It also discloses that response_format changes the shape of the output (formatted events vs raw API payload) and enumerates the returned fields. It does not mention rate limits or caching/refresh behavior, so not 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?

Front-loaded with the purpose, then when-to-use, parameters, returns, example and errors in a predictable order that is easy to scan. The full sample markdown response is somewhat long and partly redundant given an output schema exists, which keeps it from a 5.

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 read tool with 100% schema coverage and an output schema, this description covers everything an agent needs: format semantics, error conditions, and lookup scope. The only thing it repeats rather than adds is the field list of return values already captured by the output 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 coverage is 100%, so a baseline of 3 applies, and the description earns more by explaining the practical tradeoff behind response_format ('markdown' default with formatted tracking events vs 'json' raw API response for programmatic use) and giving a concrete tracking-number format example. This adds meaning beyond the schema's one-line enum description.

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+resource ('Track a shipment by tracking number') and immediately scopes it to StarShipIt, also clarifying that it covers both StarShipIt-created shipments and tracking-only orders imported via starshipit_create_tracking_order. This distinguishes it cleanly from sibling tools like starshipit_list_shipped_orders 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?

An explicit 'When to use' block states the purpose and the coverage boundary (shipments created in StarShipIt plus tracking-only orders), which is the key selection signal versus order-listing siblings. It stops short of naming a concrete alternative or when-not-to-use case, which keeps it from a 5.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false and openWorldHint=true, so safety is covered; the description goes further with the critical replace-not-merge semantics ('provide all fields, not just the changed ones, as the API replaces the entire entry') plus a full error map for 400/404/401/403. This is exactly the behavioral detail annotations cannot express.

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 purpose, then when-to-use, params, returns, errors, example — scannable and sectioned. The required/optional field enumeration largely repeats the schema, which is the only redundancy; the rest of the length is justified by the replacement warning and example.

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 purpose, routing prerequisite, replacement semantics, error conditions and a worked payload example for a 2-parameter nested-object mutation tool. With an output schema present, the brief 'Returns' line is sufficient and no agent-critical information 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%, so the baseline would be 3; the description earns an extra point by disclosing that the nested 'address' object is a full replacement (destructive-of-omitted-fields), which the schema does not convey. It loses a bit for re-listing required/optional fields the schema already documents.

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 ('Update an existing address book entry by its ID') and its sibling set makes the boundary obvious — it is not starshipit_add_address or starshipit_delete_addresses. No ambiguity about what is being mutated.

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 'When to use' block with concrete triggers (contact moved, phone changed, add delivery instructions) plus a prerequisite step: call starshipit_list_addresses first to obtain the id. That is the when-and-how an agent needs, not just implied context.

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

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

Beyond the annotations, it discloses partial-patch semantics (unprovided fields remain unchanged), the hard constraint that shipped orders cannot be updated, and specific error codes including 409 for shipped orders and 401 for invalid credentials. These are real behavioral traits an agent cannot infer from idempotentHint or destructiveHint 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?

Front-loaded with the core semantics in the first sentence, then organized under bolded When to use / Parameters / Returns / Errors headings. Every line carries operational value and there is 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?

Covers patch behavior, prerequisites, required parameter, return value, and failure modes for a nested, mutation-heavy tool. With an output schema present, the brief 'Returns' note is sufficient and nothing needed to invoke it correctly is absent.

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 the required-field fact (order_id) and the useful framing that all other fields mirror starshipit_create_order while being optional. That cross-reference to a sibling tool's shape is meaning the schema cannot convey on its own.

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 ('Update an existing unshipped order in StarShipIt') and scopes it to unshipped orders, which narrows it against siblings like starshipit_delete_order or starshipit_get_order. It does not distinguish itself from the closely related mutation siblings starshipit_update_orders_bulk and starshipit_batch_update_orders, which is the remaining gap.

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 'When to use' guidance lists concrete scenarios (correct order data, change carrier/shipping method, update address, add/replace items) and ties them to a lifecycle point ('before a label is printed'). It stops short of naming alternatives such as the bulk update tools for multi-order edits, so the when-not 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.

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

The description adds substantial behavior beyond annotations: it explains partial updates per order, notes that order_id is required in every entry, and documents return summaries with per-order errors plus 400/404/401 error conditions. It stops short of clarifying atomicity, i.e. whether a single malformed or missing order fails the whole batch or only that entry, which is a meaningful gap for a bulk mutation 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?

The description is front-loaded with the core action, then organized into clear 'When to use', 'Parameters', 'Returns', and 'Errors' sections. Every section earns its place by adding routing, parameter, or failure context without redundant wording.