consignment_calculator

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

Annotations already mark the tool as read-only, idempotent, and non-destructive, and the description adds important behavioral detail on top of that: calculations are deterministic, flags are advisory and can never imply compliance, invalid lines error with the offending field, and the API is rate-limited with a 429 body containing retry_after_seconds and Retry-After. This gives an agent a clear picture of expected behavior, error handling, and side-effect constraints beyond what annotations provide. No contradiction with 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 structured and front-loaded: the first sentence captures the core output, and subsequent paragraphs cover behavior, errors, return envelope, limitations, and related tools. Every clause earns its place — even the rate-limit and limitation notes directly affect invocation correctness — while distinct labels such as 'Behavior', 'Returns', and 'Limitations' keep it readily navigable.

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 tool with 4 parameters, nested objects, enums, an output schema, and many siblings, the description gives everything an agent needs: direct input combinations, schema, behavior, error semantics, rate-limit handling, return envelope, and explicit comparison to the alternatives. It also appropriately relies on the output schema for structural return details, but adds the meaningful caveat that flags are advisory and not compliance advice.

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 documents all parameters at 100% coverage, so the description does not need to re-explain every field. However, it adds valuable semantic context beyond the schema: the canonical vs legacy distinction, the default for mode, the IATA divisor default of 6000, and that options.container_number/awb_number trigger check-digit sanity flags. The description also clarifies that legacy items are 'dimensions in cm, weight in kg,' which the schema leaves somewhat implicit.

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 by stating the exact scope — calculate per-line and grand totals for a multi-item mixed consignment, naming each metric (CBM, LDM, volumetric weight, mode-specific chargeable figure) and the advisory flags. It differentiates the tool from siblings by explicitly labeling cbm_calculator, chargeable_weight_calculator, and ldm_calculator as 'single-figure versions' and by distinguishing shipment_summary as the tool that adds vehicle/container suggestion and duty estimates.

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 concrete guidance on when to choose this tool versus alternatives: single-figure modes are separate tools, shipment_summary is the next step for broader recommendations, and adr_lookup explains a flagged UN number. It also clarifies canonical lines[] vs legacy flat items[], and tells users to call get_subscribe_link when rate limits are hit.

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