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, covering the safe read-only nature. The description adds no extra behavioral context such as whether rates are estimates, carrier-specific quirks, or that no label is purchased. It is not misleading but contributes nothing 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 a single concise sentence that leads with the action and key scope qualifier. It contains no fluff, and the '[DEMO]' tag is a minor, harmless marker that does not detract from clarity.

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

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

Given the rich parameter schema, available output schema, and sibling tools like teapplix_purchase_label, the description adequately sets the tool's scope. It could theoretically mention that this only quotes rates and does not purchase labels, but the sibling set makes that evident. Overall, it is complete for its purpose.

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

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

Schema description coverage is 100%, with detailed parameter documentation covering the From address/saved profile shapes, Package Method constraints, ShipDate defaults, and CustomsDeclaration. The tool description itself adds no parameter semantics, 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 uses the verb 'Get' and resource 'shipping rates' with a specific qualifier, 'without an existing order', which immediately distinguishes it from the sibling tool teapplix_get_rates_for_order. This makes the tool's purpose clear and 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 phrase 'without an existing order' provides clear context for when to use this tool and implicitly points to the alternative for existing orders. However, it does not explicitly name the sibling tool or spell out when not to use it, so it falls short of a perfect score.

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 useful behavioral context: Weight/Dimensions default to the order's stored values, packages must use the same carrier, and the [DEMO] tag hints at operational status. It does not discuss rate response format or potential external API delays, but with the output schema present and read-only annotation, the additional info is sufficient.

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 and front-loaded with the main purpose. It packs essential requirements and a key default behavior without verbosity. The [DEMO] tag is a minor extra but does not hurt clarity. Every word contributes.

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 parameters, nested objects) and the rich input schema (100% coverage) plus output schema, the description is concise but sufficient. It covers the primary use case and critical behaviors, and the structured schemas fill in the rest. It lacks explicit guidance on alternatives, but that is already addressed in usage guidelines. Overall, it is complete for an agent to invoke correctly in most situations.

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 value by summarizing the required parameters and clarifying the defaulting behavior for Weight and Dimensions, which reinforces the schema but also helps the agent identify the core requirements at a glance. The 'From' parameter's dual nature (address or profile) is also echoed. This elevates it above 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 starts with a specific verb and resource: 'Get shipping rates for an existing Teapplix order.' This clearly distinguishes it from sibling tools like teapplix_get_rates (which likely handles general rate lookups without an order) and teapplix_purchase_label_for_order. The 'existing order' phrasing sets clear scope.

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 states required inputs (TxnId, From, Packages) and explains package requirements, including the carrier consistency rule and the defaulting behavior for Weight/Dimensions. It does not explicitly name alternative tools or state when not to use it, but the 'existing order' qualifier implies that other rate tools are for non-order contexts. Sibling names provide additional context, but this could be more explicit.

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

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

Annotations already declare readOnlyHint=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?

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?

The description discloses multiple behavioral traits, including operation dispatch, grouping logic, AI-managed queue configuration, and deletion restrictions. However, it contradicts the annotations: destructiveHint=false conflicts with the ability to delete queues, which is a destructive operation. This contradiction reduces transparency score to 1.

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, with three sentences covering purpose, grouping, special case, and constraints. No redundant information; front-loaded with the core CRUD action.

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-action CRUD tool with 9 parameters and an output schema, the description covers the key operational aspects and important constraints. However, it omits details like default QueueType behavior and update semantics, but these are available in the schema. The contradiction with annotations slightly reduces completeness, but overall it is adequate.

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 covers all 9 parameters with detailed descriptions, providing a baseline of 3. The description adds value by highlighting the AGENT QueueType with AgentInstructions and the deletion restrictions for built-in queues, which helps in parameter selection. It also clarifies the Operation dispatch mechanism.

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 with specific verbs 'Create, read, update, or delete' and identifies the resource as 'order queues'. It also provides distinguishing context about grouping by warehouse/shipping profile and AI-managed queues, separating it from sibling management 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 implies the tool is for queue management but does not explicitly state when to use it over alternatives or provide exclusions. However, given the clear resource (order queues) and distinct siblings, the usage context is unambiguous. It does note important constraints (deletion limitations) that guide 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?

The description explicitly lists 'delete' as an operation, but the annotations set destructiveHint to false, indicating the tool does not perform destructive side effects. This is a direct contradiction: deleting a profile is destructive. The description therefore does not provide reliable behavior disclosure.

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

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

The description is short but redundant: it lists the operations twice ('Create, read, update, or delete' and 'get/create/update/delete'). The '[DEMO]' tag is unexplained and adds noise. It remains two sentences and front-loaded, but the redundancy and tag reduce clarity.

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 11 parameters, nested objects, and an output schema, the description gives sufficient high-level context about the tool's purpose and operation dispatch. The schema handles parameter details, and the output schema covers return values, so the description is complete enough for selection and basic 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?

With 100% schema coverage, the baseline is 3. The description adds value by clarifying that Operation selects the CRUD mode and by explaining that Address and ReturnAddress correspond to the shipper/return address definitions. This goes beyond the raw schema by linking parameter groups to domain concepts.

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 creates, reads, updates, or deletes shipping profiles, explicitly listing the operations get/create/update/delete. It distinguishes from sibling tools by focusing on shipping profiles and their role in label generation.

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 tells the agent to dispatch by Operation, which is the core usage pattern for this CRUD tool. It also explains that profiles define shipper address, return address, and carrier defaults, giving context for when this tool is relevant. It does not explicitly mention alternative tools, but the resource type is unambiguous.

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 states a 'delete' operation, which is destructive, yet the annotations declare destructiveHint=false. This is a contradiction. The description does add some constraints (e.g., system tags cannot be deleted), but the contradictory safety signal is a critical flaw, warranting a score of 1.

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 concise sentences, front-loaded with the primary verb phrase. Every sentence adds value: the CRUD operation summary, the purpose of tags, and the system-tag restriction. 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 complexity (multi-operation CRUD), the description covers the main behavior and key constraint, and an output schema exists. However, the contradiction regarding destructiveHint creates a completeness gap, as the tool's destructive nature is understated. While schema covers parameters, the safety profile is misleading, so completeness is only adequate.

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 meaningful context beyond the schema: it explains that TagId 1=Ready To Ship and 2=Hold are system tags that cannot be deleted, and that tagged labels are used for visual grouping. This enriches the meaning of the TagId and Operation parameters, justifying a 4.

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, read, update, or delete order tag definitions,' which is a specific verb+resource. It also differentiates from sibling tools like 'teapplix_manage_order_tags' by focusing on tag definitions rather than applying tags to orders. The dispatch by Operation further clarifies scoping.

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: 'dispatched by Operation (get/create/update/delete)' and 'order tag definitions' signals when to use this tool. It does not explicitly name alternative tools or exclusions, but the scope is clear enough for an agent to infer usage. Lacks explicit when-not-to-use guidance, so not a 5.

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

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

Annotations carry no safety hints (all false), so the description is the primary source of behavioral disclosure. It adds valuable restrictions on deletion (WarehouseId 1 and warehouses with active dependencies cannot be deleted), which go beyond the schema's mention of WarehouseId 1. However, it doesn't describe side effects of create/update or error conditions.

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

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

Two sentences, front-loaded with the primary verb phrase and resource. Every clause adds value (CRUD scope, dispatch method, deletion constraints, demo context). 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 complexity (9 parameters, CRUD operations, type-specific behavior) and the presence of a rich schema and output schema, the description provides sufficient high-level guidance. It could mention the need for required fields on create, but the schema already covers that, so overall completeness is strong.

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 provides detailed descriptions for every parameter (100% coverage), including enums and per-operation behavior. The description adds only high-level operational context (e.g., Operation dispatch) and the delete constraint, which maps to existing parameter descriptions. Thus, the description adds marginal value 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?

The description clearly states the tool's CRUD scope ('Create, read, update, or delete warehouses') and identifies the dispatch mechanism via Operation. It distinguishes itself from sibling tools by naming the 'warehouses' resource, which no other sibling tools mention.

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 implicitly communicates when to use this tool (when managing warehouses) and provides specific usage constraints for delete operations. It doesn't explicitly name alternatives or exclusions, but since no sibling tool overlaps with warehouse management, the guidance is adequate.

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, so the description does not repeat destructive side effects. It adds context that Weight/Dimensions default to stored values and that From can be an address or profile, but does not disclose financial implications, irreversibility beyond annotations, or the meaning of the [DEMO] tag. The added value is moderate 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, with the action front-loaded and requirements summarized compactly. The [DEMO] tag is a minimal addition. Every sentence adds value without unnecessary verbosity.

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?

Despite the tool's complexity (6 parameters, nested objects, advanced options), the description gives a clear orientation of core requirements. Advanced parameters like Options, ShipDate, and CustomsDeclaration are not mentioned, but they are well-documented in the schema. The output schema further reduces the need to describe return values. The description is sufficiently complete for an agent guided by the schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates key requirements (TxnId, From, Packages, Method, weight/dimension defaults) that are already present in the schema descriptions. It does not introduce new parameter semantics beyond what the schema provides.

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

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

The description uses a specific verb ('Purchase') and resource ('shipping label for an existing Teapplix order'), clearly distinguishing it from the sibling teapplix_purchase_label. The mention of 'existing order' plus required TxnId makes the purpose unequivocal.

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

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

The description implies the tool is for existing orders by requiring TxnId, but it does not explicitly state when to use it versus alternatives like teapplix_get_rates_for_order or teapplix_purchase_label. No exclusions or alternative tool guidance are provided, so usage context 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?

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 mark readOnlyHint=true, and the description adds significant behavioral context beyond that: normalization behavior, US-only restriction with error result, and the exact meaning of each Status value ('Validated Changed' → corrected fields, 'Validated Not Changed' → no action, 'Not Changed' → rejected with Message). This is valuable operational detail.

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

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

The description is compact but information-dense: first sentence states the core function, second states the constraint, third gives actionable status handling. Each sentence earns its place, and the structure is front-loaded. The trailing [DEMO] is minor but does not hurt.

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 is present and annotations mark it read-only, the description covers the essential operational context: what the tool validates, the supported country restriction, and how to interpret the three statuses. Nothing critical is missing for an agent to invoke and process 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?

The input schema has 100% description coverage with field-level explanations and the Provider enum is documented. The description does not add additional parameter meaning beyond behavioral flow, so baseline 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'Validate and normalize a US shipping address against a carrier's validation engine.' It further distinguishes scope (US-only) and gives clear status branches, making it unambiguous what the tool does and how it differs from sibling tools around labels/orders.

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

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

It gives clear context: only US addresses supported, non-US returns error, and it instructs how to branch on Status. It does not explicitly name alternatives or say when not to use it, but the context is sufficient for an agent to select it appropriately among the siblings.

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