ActionShip by Teapplix Demo

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the agent knows this is a mutating operation. The description adds that it 'adds extra packages or splits orders', which provides some behavioral context. However, it does not disclose reversibility, side effects on labels or inventory, or any error conditions. The description adds moderate value beyond annotations.

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

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

The description is concise and front-loaded: the first sentence states the primary action, and the second sentence explains the effect. The '[DEMO]' suffix is minor noise but not redundant. Overall, it is appropriately sized with no wasted words.

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 one well-documented parameter, high schema coverage, an output schema, and annotations providing the destructive hint, the description is adequate but not thorough. It does not explain what a packing plan is, when it is available, or whether the operation is reversible—though the annotations partially cover the risk. The description is minimally complete for a simple tool, but leaves room for more context.

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

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

Schema coverage is 100% for the single parameter TxnIds, which has a clear description. The tool description adds no extra parameter semantics beyond what the schema provides. Baseline of 3 is appropriate since the schema fully documents the parameter.

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

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

The description clearly states the tool's function: applying a packing plan to one or more orders, and specifies the effects (adds extra packages or splits orders). This is a specific verb+resource combination, but it does not explicitly differentiate from sibling tools like split_order or revert_split_order, which could overlap in functionality.

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

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

The description provides no explicit guidance on when to use this tool versus alternatives. It does not mention prerequisites, exclusions, or alternatives (e.g., using split_order for manual splitting). The usage context is only implied by the function name and description, which is insufficient for an AI agent to decide between this and related 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 destructiveHint=true and readOnlyHint=false, covering the safety profile. The description adds that TxnId cancels all labels for the order, which is a useful behavioral consequence beyond a single label. However, it doesn't disclose failure modes or the Force parameter's effect on unshipped status. With annotations present, this is adequate but not rich.

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 two sentences, front-loaded with the action, followed by clear selection guidance. It contains zero redundant information and is efficiently structured.

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 5 parameters, no required fields, and an output schema, the description covers the essential selection logic. It doesn't mention the Force parameter or cancellation failure behavior, but these are documented in the schema and annotations. For a cancellation tool, this is reasonably complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by grouping parameters into mutually exclusive alternatives and noting that TxnId cancels all labels, reinforcing schema semantics. This selection logic is not explicitly encoded in the schema, so the description enhances parameter understanding.

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 'Cancel a purchased shipping label' with a specific verb and resource, clearly distinguishing it from sibling tools like purchase_label and track. The action and target are unambiguous.

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

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

The description provides explicit selection guidance: 'Provide one of: TxnId, ClientRequestId, or TrackingNumber+TrackingCarrier.' This tells the agent exactly how to invoke the tool, though it doesn't explicitly compare with alternatives like purchase_label or track. The context is clear enough for correct usage.

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 indicate non-read-only, non-destructive, and non-idempotent behavior. The description adds valuable context: it reveals the output is a base64-encoded PDF returned in "PickupDocument." It also clarifies the tool creates a manifest (a side effect), aligning with the create semantics. No contradiction with annotations.

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

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

The description is two sentences (plus a [DEMO] marker), front-loads the core purpose, and every clause provides useful information. It avoids redundancy and is appropriately sized for the tool's complexity.

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

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

Given the output schema, annotations, and full parameter descriptions, the description is largely sufficient. It covers the essential purpose and return format. It lacks explicit usage context (e.g., when a manifest is needed, how to obtain PickupDocument) but this is not critical given the structured data. Overall, the description is complete for a straightforward creation tool.

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

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

Schema description coverage is 100%: all four parameters (TxnIds, Force, Provider, AirwayBillId) have descriptions in the schema. The tool description does not add parameter-level information, so baseline 3 is appropriate since the schema fully handles parameter 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 uses the specific verb "Create" with a clear resource "carrier manifest / SCAN form" and scope "for a list of orders." This directly distinguishes it from sibling tools like teapplix_purchase_label or teapplix_get_orders by describing a distinct operation.

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

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

The phrase "for a list of orders" implies the tool should be used when generating a manifest from order IDs, but it does not explicitly state when to use this tool versus alternatives, nor does it mention exclusions or prerequisites. No alternative tools are named, giving only 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?

Annotations already indicate destructiveHint=true and readOnlyHint=false, so the description doesn't need to reiterate that this is a write operation. However, it adds only 'Per-row Status is one of: Accepted, Declined, Exists' and '[DEMO]'—neither of which discloses side effects, idempotency, or failure modes. This is minimal value beyond the annotations.

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

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

The description is very concise and front-loads the main purpose in one sentence. The inclusion of the per-row status and '[DEMO]' adds minor extra information but is still efficient and not 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?

Given the extremely rich input schema, annotations, and presence of an output schema, the description is minimally sufficient for understanding what the tool does. However, it lacks usage guidelines and any behavioral context beyond the raw create action, making it adequate but with clear gaps.

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

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

Schema description coverage is 100%, with all parameters fully described in the input schema. The description adds no parameter-level meaning beyond the schema, so the baseline score of 3 applies.

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

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

The description clearly states the tool's function: 'Create one or more orders in Teapplix.' This is a specific verb (create) and resource (orders). While it doesn't explicitly differentiate from sibling teapplix_update_order, the 'create' verb and mention of 'one or more' sufficiently convey the core purpose.

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

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

The description provides no guidance on when to use this tool versus alternatives like teapplix_update_order or teapplix_purchase_label. It lacks any mention of prerequisites, exclusions, or scenarios where a different tool would be preferred, so the agent is left without contextual usage direction.

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?

Since annotations are generic (all false) with no readOnly or destructive hints, the description carries the full burden for behavioral disclosure. It mentions 'Generate' but does not disclose side effects such as order status changes, costs, or implications of ForceRegen beyond what the schema states. This is a gap for a write operation.

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 two sentences that are well-structured and front-loaded: the first states the core function, the second adds crucial context. The [DEMO] tag is extra but not distracting. Every sentence earns its place without redundancy.

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

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

Given the presence of a full output schema and complete parameter descriptions, the description provides sufficient context for basic invocation. It covers the main use case and exclusions but omits side-effect caveats, which are relevant but covered under behavioral transparency.

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

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

The input schema already includes detailed descriptions for all three parameters (TxnIds, ProfileId, ForceRegen) with 100% coverage. The description adds no additional parameter-specific meaning, so it relies on the schema as 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 clearly states 'Generate an SSCC pallet label' and specifies the exact use case ('bulk B2B shipments', 'EDI retailer orders') with concrete examples (Home Depot, Walmart). It distinguishes itself from sibling label tools by explicitly noting it is 'not for individual consumer 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?

The description gives explicit when-to-use ('bulk B2B shipments to distributors or 3PL warehouses', 'EDI retailer orders that require GS1-compliant container labels') and when-not-to-use ('not for individual consumer orders'). However, it does not name a specific alternative sibling tool, so it does not fully meet the 'alternatives' criterion.

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=true, so the read-only nature is known. The description adds valuable behavioral context: the requirement for at least one filter and the pagination loop (PageNumber until >= TotalPages), which are not derivable from annotations. This goes beyond the structured metadata.

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 concise and front-loaded with the main purpose. The list of acceptable filter parameters is necessary and not wasteful. The 'IMPORTANT' pagination note is a useful highlight. The trailing '[DEMO]' is minor noise but doesn't detract significantly.

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 tool's complexity (22 parameters) and the presence of an output schema, the description covers the two most critical operational aspects: mandatory filter requirement and pagination. It doesn't need to explain return structure since the output schema exists. This is adequate and complete for safe 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 description coverage is 100%, so the baseline is 3. The description adds cross-parameter semantics by enumerating which parameters can satisfy the 'at least one required' constraint, and clarifies pagination parameters' relationship. This is meaningful additive value beyond individual schema descriptions.

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

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

The description clearly states the tool's function: 'Download / query orders from Teapplix.' This is a specific verb+resource combination that distinguishes it from sibling tools like teapplix_create_order, teapplix_update_order, and teapplix_manage_order_tags. The scope is unambiguous.

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

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

The description provides clear usage context by specifying that at least one of several filters is required (TxnId, QueueId, Tag, etc.) and gives explicit pagination instructions. It doesn't explicitly mention alternatives or when-not-to-use, but the required-filter condition is strong guidance for correct invocation.

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 concrete behavioral details beyond the read-only annotation: it specifies the default fields (InsuranceType, Delivery.Signature, Delivery.Residential), the carrier-specific Options tree via DetailLevel, and the HTTP 409 error for cancelled/split orders. This enriches the agent's understanding of the tool's 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?

The description is two compact sentences with the main action first, followed by optional behavior and an error condition. No wasted words.

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 tool's simplicity (one required param, optional detail level), the presence of an output schema, and readOnly annotation, the description covers the essential behavioral facts including an error case. It is complete for agent use.

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 covers both parameters with clear descriptions (100% coverage). The description adds a bit more specificity on field names but doesn't introduce new semantics beyond the schema. Baseline for high schema coverage is 3.

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

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

The description uses 'Retrieve' as a specific verb and 'current shipping options for an order' as the resource, clearly distinguishing it from sibling tools like teapplix_set_order_ship_options, which modifies options.

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 explains default behavior and the DetailLevel parameter for carrier-specific options, and notes the HTTP 409 condition for cancelled or split orders, providing clear usage context. It doesn't explicitly name alternatives, but the context is sufficient.

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=true and openWorldHint=false, so the safety profile is covered. The description adds the semantic role of queues (warehouse/shipping-profile grouping), but says nothing about pagination, result volume, or auth needs; the '[DEMO]' tag is unexplained and adds ambiguity rather than context.

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

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

Two compact sentences front-load the core action and filters, with no wasted prose. The trailing '[DEMO]' marker is the only element of unclear value.

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

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

Return values are covered by the existing output schema, so the description needn't explain them. For a simple filtered-list tool, what remains is a minor gap around paging and the meaning of the DEMO tag.

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 each of the five filters is already documented in the schema. The description restates the filter names without adding format details (e.g., substring semantics for QueueName, which the schema covers), so the baseline 3 applies.

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

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

States a clear verb+resource ('List order queues') and enumerates the filterable fields, so an agent can tell this is a read/list operation. It doesn't explicitly differentiate from the sibling teapplix_manage_queue, leaving that inference to the agent.

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 implies usage by noting filters are optional and explaining that queues group orders by warehouse and shipping profile, but gives no explicit when-to-use/when-not guidance or pointer to teapplix_manage_queue for creation/modification.

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=true and openWorldHint=true, so the safety profile is covered. The description adds the useful behavioral fact that no pre-existing order or state is required, but the '[DEMO]' marker is unexplained — an agent cannot tell whether it means sandbox data, a demo carrier account, or a deprecated tool, which introduces ambiguity rather than clarity.

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

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

Two short fragments, front-loaded with the core action and scope — nothing padded. The trailing '[DEMO]' is unexplained noise that slightly dilutes 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 tool with 6 params, nested address/package objects, an enum, and an output schema, the description covers only the purpose and the no-order scope; carrier-consistency, RATESHOP vs direct methods, and Provider behavior live entirely in the schema. Because the output schema exists, return values needn't be explained, but the description is thinner than the tool's complexity warrants.

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 From/To/Packages/Provider/ShipDate fields are all richly documented in the schema itself, so the baseline of 3 applies. The description contributes no additional parameter meaning, but it also loses nothing since the schema carries the load.

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 shipping rates') and adds a scoping qualifier ('for a shipment without an existing order') that separates it from the sibling get_rates_for_order. It stops short of naming the sibling explicitly, so the differentiation is implicit rather than spelled out.

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

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

The phrase 'without an existing order' implies the selection rule: use this when no order exists, use get_rates_for_order otherwise. There is no explicit 'use X instead when...' statement, and nothing says what to do when an order does exist or how this relates to get_order_ship_options or purchase_label.

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=true and openWorldHint=true, covering the safety profile. The description adds one genuinely useful behavioral flag, the '[DEMO]' marker, plus the note that Weight/Dimensions silently fall back to stored order values. It says nothing about latency, rate-limiting, or how failed carrier lookups behave.

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

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

Three tight sentences with the resource named first and the required inputs following; nothing is padding. The trailing '[DEMO]' tag is terse but its meaning is unexplained, slightly weakening the structure.

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 an output schema present and full parameter coverage in the schema, the description need not explain return values or optional fields, and it correctly front-loads the three required inputs. Its one real gap is the unresolved overlap with the sibling teapplix_get_rates tool, which the description never addresses.

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 parameter exhaustively, including the defaulting behavior the description restates. The description adds no syntax, format, or constraint detail beyond what the schema provides, so the baseline of 3 is correct.

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

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

States a specific verb and resource ('Get shipping rates for an existing Teapplix order'), which distinguishes it from the bare rate tool by anchoring it to an order. However, it never names teapplix_get_rates or teapplix_get_order_ship_options, so the agent must infer the boundary rather than being told.

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 enumerates required inputs (TxnId, From, Packages) which implies usage 'when you have an existing order', but gives no explicit when-to-use vs. when-not guidance and no routing to the sibling rate/ship-option tools. Rich guidance about Method, RATESHOP, and Provider lives in the schema rather than the description.

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=true, and the description does not contradict that. The description adds valuable context beyond the annotation by disclosing data scale (200+ methods), the meaning of the Name field as a constant to consume, and filterability. This goes beyond the minimal read-only hint.

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 consists of three sentences that front-load the primary purpose, then provide usage examples and the calling pattern. Every sentence earns its place, and the '[DEMO]' marker is a minimal but relevant note. No redundancy or 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?

Given the tool's simplicity (no required parameters, output schema present), the description is complete. It tells the caller how to invoke (no-args vs filter), what the output represents (constants for Method), and the scale (200+ methods). Nothing essential is missing for a read-only lookup of this type.

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%: Carrier has examples, PackageType has enum and explanation. The description does not add meaning beyond the schema; it only restates the Carrier filter option and mentions scale. This matches the baseline 3 for full schema coverage.

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

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

The description explicitly states the tool 'Returns supported shipping method constants, carrier, and package type,' which is a specific verb+resource that distinguishes it from sibling tools like get_rates (pricing) and get_order_ship_options (order-specific options). It further clarifies the purpose by explaining that the Name field is used in Packages[].Method for rate quotes and label purchase.

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 provides explicit usage instructions: 'Call with no parameters for all 200+ methods; filter by Carrier (USPS, FEDEX, UPS, etc.) for a shorter list.' It also ties the output to a concrete downstream use case. However, it does not explicitly name alternative tools or when-not-to-use scenarios, so it does not fully meet the 5-level criterion.

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=true and openWorldHint=false, so safety is covered; the description goes further by explaining that profiles carry shipper/return addresses and carrier credentials, that CarrierInfo is read-only, and by disclosing two non-obvious behaviors (BillThirdParty=true suppresses rate quotes on UPS/FedEx; InheritedFromMaster=true borrows master credentials). That is real value beyond the annotations, though it says nothing about result volume or pagination.

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 filters, then moves to domain behavior; every sentence carries information and none is redundant. The trailing '[DEMO]' marker is slightly noisy but does not obscure the content.

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 an output schema present, return-shape explanation is not required, and the description still pre-empts confusion about the CarrierInfo array. Combined with full schema coverage and clear annotations, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100%, so the three filter parameters are already fully documented with types and meanings. The description only restates them by name without adding matching semantics (e.g., exact vs partial name matching, whether filters combine with AND). 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?

Opens with a specific verb+resource ('List shipping profiles') plus the available filter dimensions, which is unambiguous. It doesn't explicitly name teapplix_manage_shipping_profile as the mutation counterpart, so the read/write split is only implied by the verb.

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 filter list hints at how to narrow results, but there is no explicit when-to-use or when-not-to-use guidance, and no mention of the sibling teapplix_manage_shipping_profile that would be the alternative for creating or editing profiles. Usage is inferable but not 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds useful domain context (tags are colored order labels) but says nothing about result volume, ordering, or whether an empty filter returns all tags — modest value beyond structured fields.

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

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

Two short, front-loaded sentences: purpose first, domain gloss second. The trailing '[DEMO]' marker is noise, but the rest is efficiently sized with no 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?

An output schema exists and annotations cover the safety profile, so the description needn't explain return values. For a simple 2-optional-filter listing tool, what remains is only the missing sibling routing, which is a minor 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% and both parameters are documented in-schema, including the substring-match behavior for TagName. The description only restates that filtering is optional by TagId or TagName, adding no syntax, format, or matching nuance 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?

States a specific verb and resource ('List tag definitions') plus the domain meaning of a tag ('colored labels applied to orders'). It reads clearly as the read-only listing counterpart to teapplix_manage_tag and teapplix_manage_order_tags, though it never names those siblings explicitly.

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

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

The description notes the optional filters but gives no guidance on when to call this versus teapplix_manage_tag (definition CRUD) or teapplix_manage_order_tags (applying tags to orders). An agent must infer the read-vs-write split from tool names alone.

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=true and openWorldHint=false, so the safety profile is covered. The description adds only that filters are optional; it leaves the "[DEMO]" marker unexplained, which could confuse an agent about whether this hits live data or a sandbox.

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

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

A single front-loaded sentence that earns its place; the trailing "[DEMO]" tag is the only questionable element since its meaning is never defined.

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, so return values need no explanation, and annotations cover read-only semantics. What's missing is the read-vs-write relationship to the sibling manage tool and any note about result size or pagination for an unfiltered list.

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 matching semantics (exact ID, case-insensitive substring, type examples like GENERIC/FBA/ECCANGWMS). The description merely restates the three parameter names and adds nothing beyond them, 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?

Specific verb and resource ("List warehouses") plus the filterable fields. It does not distinguish itself from the sibling teapplix_manage_warehouse (create/update), so an agent must infer that this is the read counterpart.

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

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

"Optionally filtered by" implies that calling with no parameters returns everything and that filters are narrowing, which is useful. But there is no explicit when-to-use guidance and no mention of teapplix_manage_warehouse as the alternative for mutations.

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 behavioral detail by stating that each route returns a computed Zone or an Error sub-object explaining why zone lookup failed. This goes beyond the readOnlyHint and openWorldHint annotations, though it does not cover rate limits or prerequisites.

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 two sentences long, with the main action in the first sentence and output behavior in the second. It is front-loaded and free of unnecessary detail, earning a perfect score.

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 tool's low complexity (one array parameter), full schema coverage, and presence of an output schema, the description provides sufficient context. The error behavior disclosure covers the only non-obvious aspect, making it complete.

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

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

The input schema fully describes all three parameters (Carrier, OriginZip, DestinationZip) with 100% coverage, so the description provides no additional parameter-specific insight. The baseline of 3 is appropriate since the schema does the heavy lifting.

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 explicitly states 'Calculate carrier shipping zones between origin and destination ZIP codes,' which identifies a specific verb and resource. This clearly distinguishes the tool from siblings like get_rates or validate_address by focusing on zone calculation.

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

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

The description gives clear context that the tool is for calculating shipping zones between ZIP codes, but it does not mention alternative tools or exclusions. This matches the rubric's 'clear context, no exclusions' level, justifying a 4.

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 mark readOnlyHint=true and openWorldHint=false. The description adds usage context (when tools list is truncated) and discloses the behavior of the 'shipping_methods' topic, though it doesn't describe response format or pagination. No contradiction.

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

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

Three sentences, each serving a purpose: state function, give usage trigger, provide alternative. No wasteful 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?

The tool is straightforward with one optional parameter and no output schema. The description explains when to use it, what it returns, and distinguishes from a sibling tool. It doesn't enumerate all possible topics, but the parameter schema covers that. [DEMO] hint may reduce reliability confidence, but not a completeness 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% with the Topic parameter described fully, including the shipping_methods example. The description does not add additional parameter details beyond what the schema already states, only restating the same example.

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

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

Description uses specific verb 'Returns' and identifies the resource 'full Teapplix MCP tool catalog grouped by category.' It distinguishes from siblings by naming teapplix_get_ship_methods as the live alternative.

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

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

Explicitly states when to call: 'when you cannot find a tool or suspect the tools list was truncated.' Also names an alternative tool for a specific sub-case ('Use teapplix_get_ship_methods to get the live list of valid shipping method codes').

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?

With all annotations false, the description carries the burden of disclosing side effects. It only states the operations (get/add/remove) which are already present in the schema. It does not mention that add/remove mutate order state, any permission requirements, or potential impacts, so transparency is low.

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 extremely concise and front-loaded, stating the core function in a single sentence. The '[DEMO]' suffix is a minor extra but does not detract from efficiency.

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, so return values are covered. However, as a mutation tool with no annotations, the description lacks usage guidance and behavioral warnings. It is adequate for a basic understanding but leaves gaps for safe 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 description coverage is 100%, so the schema fully documents all parameters. The description adds no additional parameter semantics beyond what the schema provides, meriting the baseline score of 3.

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

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

The description 'Get, add, or remove tags on orders' uses a specific verb and resource, clearly stating the tool's scope. It distinguishes itself from the sibling 'teapplix_manage_tag' by focusing on order tags, and from other order-related tools by its tag-specific purpose.

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

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

The description provides clear context: it is for managing tags on orders, which implies when to use it. However, it does not explicitly exclude alternatives or mention when not to use it, so it lacks full usage 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?

Beyond the annotations it discloses the meaningful consequences: which queues are undeletable, that AGENT-type queues are driven by Markdown AgentInstructions, and the default QueueType of DISPLAY. There is mild tension with destructiveHint=false since deletion is supported, but the description compensates by spelling out exactly when deletion is blocked, so an agent is not misled about risk.

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

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

Four tight sentences front-loaded with the operation dispatch and ending with the sibling pointer and demo tag. No filler, though the '[DEMO]' marker is noise for invocation decisions.

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, full annotations, and 100% schema coverage, the description supplies the missing operational context: dispatch semantics, AGENT-queue behavior, and delete preconditions. Only the not-found/name-collision handling on update is unaddressed.

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 parameter meaning is already fully documented per-field. The description restates a few key points (QueueType=AGENT pairing with AgentInstructions, built-in QueueId range) but adds no format/syntax detail beyond the schema; baseline 3 is appropriate when the schema does the heavy lifting.

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 set and resource ('Create, update, or delete order queues') and explains the dispatch mechanism via Operation. It also states what a queue is conceptually (grouping orders by warehouse and shipping profile), which separates it cleanly from sibling tools like teapplix_get_queues or teapplix_manage_warehouse.

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

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

It names the read counterpart explicitly ('Use teapplix_get_queues to list existing queues') and gives hard preconditions for delete (built-in queues 1-4 and queues with active orders cannot be deleted). It stops short of saying when to choose update vs create for an existing queue, or what to do when a QueueName collides, so it is clear but not fully 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?

The description states the tool can 'delete' a profile that is removed, while annotations declare destructiveHint=false, so the safety signal an agent relies on is undercut for one of the three operations; it also stays silent on delete side effects (e.g. whether a profile in use by open shipments can be removed). It does add real value beyond the schema by flagging that carrier credentials are managed elsewhere and are not modifiable here.

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?

Purpose and dispatch mechanism are front-loaded, followed by scope (addresses, not credentials) and sibling routing — no wasted sentences. The trailing '[DEMO]' marker and the slightly redundant 'dispatched by Operation' phrasing keep it from being fully tight.

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 multi-operation mutation tool with 11 parameters and a 100%-described schema plus an output schema, the description covers purpose, sibling routing, and the main scope exclusion. The remaining gap is delete semantics — consequences and preconditions for removing a profile are 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 coverage is 100% and the schema itself documents the Operation enum, ProfileName/ProfileId requirements per operation, and nested address fields (including the ReturnAddress-defaults-to-Address rule). The description adds no parameter-level detail beyond that, which is the expected baseline when the schema does the work.

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 specific verbs plus the resource: 'Create, update, or delete shipping profiles, dispatched by Operation.' The operation-dispatch pattern is called out explicitly, and the sibling read tool teapplix_get_shipping_profiles is named, so an agent can distinguish mutating vs listing behavior immediately.

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

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

Explicit routing: 'Use teapplix_get_shipping_profiles to list existing profiles,' and an explicit exclusion: carrier account setup 'is managed separately in Teapplix and cannot be changed through this tool.' This covers when to use it, when to use a sibling instead, and what it cannot do.

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 advertises deletion of tag definitions ('delete: remove tag'), yet annotations declare destructiveHint=false, which per MCP semantics means the tool only performs additive updates. That mismatch matters for an agent deciding whether a delete is safe or reversible. The system-tag protection note (TagId 1/2 cannot be deleted) is useful, but the write-profile contradiction dominates.

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

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

Three short sentences, front-loaded with the verb/resource and the dispatch mechanism, then the domain context, then the constraint and sibling pointer. No sentence is filler, apart from a trivial '[DEMO]' tag.

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 4-parameter mutation tool with a full schema and an output schema, the description covers dispatch, required fields per operation, constraints on system tags, and where to list tags. It omits whether deletes are permanent, whether update can rename a tag, and how duplicate-name errors behave, but the essentials for correct invocation are present.

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

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

Schema coverage is 100% so the baseline is 3, and the description adds genuine value on top: it names the concrete system tag IDs (1=Ready To Ship, 2=Hold) that are immune to delete, and reiterates per-operation requirements for TagId/TagName/Color. This goes beyond the schema's generic field notes.

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 specific verbs (create/update/delete) and a specific resource (order tag definitions), dispatched by the Operation enum, and clarifies that tags are colored labels on orders. It does not explicitly separate itself from the sibling teapplix_manage_order_tags (which appears to apply tags to orders rather than define them), leaving one plausible confusion unresolved.

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?

Provides clear context: Operation selects create/update/delete, and it names teapplix_get_tags as the tool for listing existing tags. It is clear about the happy path but offers no exclusion against teapplix_manage_order_tags, so the when-not is only implied.

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 explicitly advertises deletion ('delete warehouses', 'cannot be deleted') while the annotations declare destructiveHint=false, which per MCP semantics means non-destructive/additive only. An agent trusting the annotation could invoke a delete without confirmation. The description does add useful constraint context, but the direct conflict with the annotation is disqualifying.

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

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

Three tight sentences: operation dispatch first, then deletion constraints, then the listing alternative. No filler, though the trailing '[DEMO]' marker is noise.

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, so return values need no explanation, and the schema carries all parameter detail. The description covers the mutation scope and the key guardrails; only confirmation/permission expectations for destructive operations are 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 Operation, WarehouseType, WarehouseId, and the 3PL fields are already fully documented in structured form. The description only restates the Operation dispatch and the WarehouseId 1 restriction, adding nothing 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 set and resource ('Create, update, or delete warehouses') and immediately explains the dispatch mechanism (Operation). It is clearly distinguished from the read-only sibling teapplix_get_warehouses, which it names explicitly.

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

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

Explicitly routes listing to teapplix_get_warehouses and states the two deletion preconditions (WarehouseId 1 is undeletable; warehouses with active orders, channel mappings, or listings cannot be deleted). It does not explain when to prefer create vs update vs delete, though the schema's Operation enum covers that.

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?

With annotations providing idempotentHint=true, destructiveHint=false, and readOnlyHint=false, the description adds the important return-value nuance ('single scalar status, not a per-order array'). This helps prevent the agent from expecting an array, adding behavioral context beyond annotations.

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

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

The description is two sentences with no fluff. The first sentence states the action, the second clarifies the return type. The [DEMO] marker is a minor artifact but doesn't detract.

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 flagging operation with an output schema and sufficient annotations, the description covers the essential nuance (scalar return). It doesn't explain side effects, but the operation is simple and the annotations cover safety. A minor gap is the lack of context on when manual review is triggered.

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 documents the only parameter with a clear description. The description's repetition of 'one or more orders' adds no new syntax or format details. Baseline 3 is appropriate given 100% schema coverage.

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

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

The description uses the specific verb 'Mark' with the resource 'orders for manual review', clearly stating the operation. The added note about returning a scalar status adds specificity, distinguishing its output contract.

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

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

No guidance is provided about when to use this tool versus alternatives like teapplix_manage_queue or teapplix_update_order. There is no mention of prerequisites, ordering, or when manual review is appropriate.

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 convey non-read-only, destructive, and non-idempotent behavior, lowering the burden on the description. The description adds valuable context about the response structure (LabelData for label bytes, DocumentsData for additional carrier documents) and the [DEMO] marker, giving the agent insight into what to expect from the output.

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 brief and front-loaded with the action ('Purchase'), followed by the key differentiator and output format. Every sentence adds distinct value, and the [DEMO] marker is a concise extra note. No fluff or redundancy.

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

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

Given the tool's complexity (9 params, nested objects, output schema present), the description provides the essential context: standalone use, response structure, and demo status. The rich schema handles parameter details, and the annotations provide safety behavior. A warning about costs or non-refundability could improve it, but the combination of schema, annotations, and description is largely complete.

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

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

The schema has 100% documentation coverage, so the baseline is 3. The description adds no parameter-specific meaning beyond what the schema already provides; however, it does not need to, as the schema descriptions are exhaustive. The mention of LabelData/DocumentsData relates to output, not input parameters.

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

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

The description uses a specific verb ('Purchase') and resource ('shipping label'), clearly distinguishing it as a standalone label purchase. It explicitly notes that no existing Teapplix order is required, which differentiates it from teapplix_purchase_label_for_order and other siblings.

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

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

The description clearly states when to use this tool: for standalone labels without an existing order. It does not explicitly name alternatives (e.g., teapplix_purchase_label_for_order), but the sibling name and the 'standalone' qualifier imply the distinction. No exclusions or prerequisites are mentioned, but the key context is provided.

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, openWorldHint=true, and idempotentHint=false, so the irreversible/real-world nature of a label purchase is partially covered. The description adds the useful defaulting rule for Weight/Dimensions but does not say that this spends money, that cancel_label is the reversal path, or what the unexplained '[DEMO]' tag implies. With annotations carrying the safety profile, a 3 is fair.

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

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

Two tightly written sentences that front-load the action and required inputs; little waste. The bracketed '[DEMO]' tag is unexplained and slightly dilutes an otherwise clean structure.

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 a rich input schema, an output schema, and annotations covering safety, the description need not explain return values. It is nonetheless thin for a destructive purchase tool: no routing versus teapplix_purchase_label / get_rates_for_order, no note on cost or reversal, and an unexplained demo marker.

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 seven parameters including nested From/Packages shapes are already documented in the schema. The description restates the three required params and the Weight/Dimensions defaults, but that defaulting rule is also present verbatim in the schema, so added value is minimal. Baseline 3.

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

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

States a specific verb and resource (purchase a shipping label) scoped to an existing Teapplix order, which an agent can act on directly. It does not, however, distinguish this from the near-identical sibling teapplix_purchase_label, leaving ambiguity about which of the two applies.

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

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

No when-to-use guidance, no prerequisites (e.g. rates should be fetched first), and no reference to alternatives. Most notably it never acknowledges the sibling teapplix_purchase_label, so an agent has no basis for choosing between the two.

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 readOnlyHint=false. The description adds no additional behavioral details (e.g., what happens to child orders, reversibility, or error states) beyond stating the revert intent. It does not contradict annotations but also enriches them minimally.

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 a single, concise sentence with no filler. '[DEMO]' is a minor suffix but does not detract from clarity or structure.

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 one-parameter destructive operation with annotations and an existing output schema, the description provides sufficient context. It could mention prerequisites or failure modes, but 'previously split order' implies the main prerequisite, and the schema covers the parameter.

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

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

Schema description coverage is 100%, with the TxnId parameter documented as 'TxnId of the original (parent) order to revert.' The description adds no extra semantic details beyond the schema, but the schema fully covers the 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 description states a specific verb ('revert'), resource ('previously split order'), and outcome ('back to a single order'). It clearly distinguishes from sibling tools like teapplix_split_order and teapplix_split_order_cont.

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 clearly implies when to use this tool: after an order has been split and you want to undo that split. It does not explicitly list alternatives or exclusions, but the context is unambiguous given the tool name and sibling set.

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 indicate idempotent and non-destructive behavior, but the description adds critical context by disclosing that providing Packages replaces all existing package definitions. This is valuable behavioral information beyond what annotations convey, and it does not contradict them.

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 concise (4 sentences), front-loaded with purpose, and every sentence serves a distinct function: purpose, alternative guidance, restrictive use case, and a caveat. No unnecessary repetition or fluff.

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 tool's complexity (nested objects, multiple advanced options) and rich schema, the description adequately covers what it does, when to use it, and a key behavioral caveat. The output schema handles return-value documentation, so no further explanation is needed.

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% with detailed descriptions, so the baseline is 3. The description adds value by explaining when Packages is required (for setting Options or CustomsOptions) and clarifying its replacement semantics, which enriches understanding beyond the schema alone.

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

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

The description clearly states the tool's purpose: 'Set carrier-specific advanced shipping options (Service flags, COD) and CustomsOptions.' It distinguishes from sibling teapplix_update_order by explicitly naming when to use which tool, making its role unique.

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

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

The description provides explicit usage guidance: prefer teapplix_update_order for common sparse options, and use this tool only when Service, COD, or CustomsOptions fields are needed. It also warns about Packages replacing existing definitions, giving clear when-to-use and when-not-to-use 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?

Annotations already declare destructiveHint=true and readOnlyHint=false, so the bar is lower. The description adds context about the mechanism (dividing line items) and positions this as the normal workflow, but does not disclose reversibility or side effects beyond the annotations. This merits a 4 rather than 3 due to the added context.

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

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

The description is efficiently structured, with the first sentence giving the core purpose and the next two providing usage guidance. However, the trailing '[DEMO]' artifact adds no value and reduces clarity, making a 4 instead of 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 complex, destructive operation, the description is adequate but misses important context about reversibility (e.g., that teapplix_revert_split_order exists) and any preconditions beyond the split_order_cont exclusion. The rich schema and annotations compensate somewhat, but the gap justifies a 3.

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

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

Schema description coverage is 100% with detailed descriptions for all parameters and nested properties. The description does not add parameter-specific details, so the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource ('Split an order into multiple child orders') and clearly distinguishes from the sibling tool split_order_cont by naming it and its specialized purpose. The mechanism ('by dividing its line items') adds clarity.

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

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

The description gives explicit guidance on when to use ('normal split workflow') and when not to ('Do not use split_order_cont — that is a specialized follow-up for orders with "Hold" children'), naming the alternative and the condition for its use.

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 readOnlyHint=false, so the safety profile is known. The description adds valuable context about the precise operational scenario (hold child re-split), but does not disclose additional behavioral details such as whether the original hold child is removed or modified, or any irreversibility beyond the annotation. That leaves some gaps, but the description is not misleading.

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

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

Three sentences, front-loaded with the core purpose, followed by scenario clarification and an explicit exclusion. No wasted words; the [DEMO] tag is a minor non-semantic appendage that doesn't detract.

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

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

The description is complete enough for a specialized continuation operation, clearly explaining the split scenario and pointing to the correct sibling for normal cases. The extensive schema and output schema cover remaining details. It could mention prerequisites or what happens to the original hold order, but this is not essential for selecting and invoking the tool.

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

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

Schema coverage is 100% for the two parameters, and the schema includes detailed descriptions for TxnId and Orders, including nested fields. The description itself adds no parameter-specific information, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's specific purpose: further splitting an order that has a 'Hold' child, in the specialized restock scenario. It uses a specific verb ('split') and resource ('order'), and explicitly distinguishes it from normal splits by naming the alternative (split_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 description provides explicit when-to-use guidance (when a hold child needs to be split after restocking) and when-not-to-use guidance ('Do not use this for normal splits — use split_order instead.'). This fully addresses selection vs. siblings.

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 indicate readOnlyHint=false and idempotentHint=false, signaling a non-read-only, non-idempotent operation. The description adds behavioral insight by explaining the dual-path (submit/review) behavior and the possible status outcomes (Accepted, Declined, NotFound). It does not contradict annotations and provides context beyond the structured flags.

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

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

The description is three sentences, all informative and free of fluff. It front-loads the main action, then adds relevant details about paths, status, and parameter discovery. The [DEMO] tag is minor noise but does not detract from conciseness.

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 tool's complexity (6 params, nested object, multiple paths), the description covers key aspects: the purpose, the two modes, status values, and a useful parameter tip. The existence of an output schema and full schema descriptions reduces the need to detail return values. It could have elaborated more on account prerequisites or the submit/review difference, but it is sufficiently complete for an agent to use.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds valuable guidance for the ShipMethod parameter by advising the use of teapplix_get_ship_methods with Carrier=<3PLType> to discover valid values. This goes beyond the schema's generic description, enhancing semantic understanding.

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

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

The description clearly states the tool's function: 'Submit an order to a 3PL vendor for fulfillment.' It uses a specific verb ('Submit') and resource ('order to 3PL'), and differentiates from siblings by focusing on 3PL submission. It also specifies handling of both unshipped and already-shipped orders, adding clarity.

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

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

The description provides clear context for when to use the tool: for submitting orders to a 3PL, including the submit path for unshipped and review path for already-shipped orders. It also gives a practical tip to use teapplix_get_ship_methods to discover valid ShipMethod values. However, it does not explicitly contrast with sibling tools or state when not to use it, which would have pushed it to 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=true, and the description adds valuable behavioral context by specifying the return format: 'a delivery summary plus a chronological TrackingEvents array.' The '[DEMO]' flag also indicates a demo mode. This goes beyond what annotations provide.

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

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

The description is a single, well-structured sentence that communicates purpose, required inputs, and output behavior with no wasted words. It is appropriately front-loaded and concise.

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 tracking tool with an output schema present, the description fully covers the tool's purpose and return behavior. The readOnlyHint annotation addresses safety, and the output schema covers return details. No significant gaps remain.

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 both parameters. The description only restates the parameter names ('by carrier and tracking number') without adding additional semantic context, so it meets the baseline but doesn't elevate it.

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

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

The description clearly states the tool's function: 'Track a shipment by carrier and tracking number.' It specifies both the verb and resource, and distinguishes itself from sibling tools by focusing on tracking, which no other tool covers.

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

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

The description implies when to use the tool (when you need to track a shipment) but provides no explicit guidance on alternatives or exclusions. Since there are no sibling tracking tools, the context is clear, but it lacks explicit 'when to use vs. alternatives' language.

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 indicate destructiveHint=true and readOnlyHint=false; the description adds valuable destructive semantics: TagList 'fully replaces existing tags,' ShippingDetails 'replaces all existing packages,' and AppendMode toggles append vs replace. It also discloses the per-row Status enum values. No contradictions with annotations.

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

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

The description is a single dense paragraph that front-loads the core purpose. It efficiently lists key fields and behaviors, though the [DEMO] suffix is noise and the structure could benefit from bullet points for readability. It earns its length for a complex 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 complex mutation tool, the description covers all major capabilities, replacement behaviors, and the correct alternative for insurance type. The schema provides full parameter details and an output schema exists, so the lack of return-value discussion is acceptable. It could mention that Orders is an array and TxnId is required, but these are visible in 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 the schema already documents parameters in detail. The description contributes a high-level field summary (top-level, sub-objects) and adds the per-row Status enum values, which are not present in the input schema. This goes beyond simple repetition, though most details are mirrored in 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?

The description opens with 'Update existing orders in Teapplix'—a clear verb+resource pair. It distinguishes from siblings by listing specific updatable fields and explicitly routing InsuranceType to setOrderShipOptions, differentiating from related tools like create_order and manage_* 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?

The description provides an explicit alternative: 'For InsuranceType use setOrderShipOptions.' It also implies when to use this tool (for order-level updates including payment status, address, items, tags, queue, warehouse, memos, shipping details) but does not explicitly enumerate exclusions such as tag-only updates using manage_order_tags. This is clear context with one explicit alternative, but not comprehensive.

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=true and openWorldHint=false, so safety is covered; the description goes further by disclosing the failure mode (non-US input errors out) and, critically, the tri-state Status semantics including that 'Validated Changed' means the engine mutated fields and the caller must diff and update. That is behavior beyond the annotations and essential to correct consumption.

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 scope, then a compact status branch list; every sentence earns its place. The trailing '[DEMO]' marker is noise that slightly clutters 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?

An output schema exists, so return-shape explanation is unnecessary; combined with annotations covering safety and a 100% documented schema, the description fills the remaining gaps (US-only restriction, status-driven next actions) completely for an agent to call and act on results.

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 nested Address fields and the Provider enum/fallback logic are already fully documented in structured data. The description only reinforces the CountryCode=US constraint, adding little beyond the schema — baseline 3.

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

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

States a specific verb pair (validate and normalize) plus the precise resource (a US shipping address) and the engine it consults. It is the only address-validation tool among the siblings, and the description makes the US-only scope explicit so it can't be confused with rate, label, or order 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?

Gives explicit when-to-use conditions ('Only US addresses (CountryCode=US) are supported — non-US addresses return an error') and a full branch table telling the agent what action to take for each Status value. This is actionable routing guidance rather than a generic blurb.

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