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

Annotations (readOnly, idempotent, non-destructive) set a low bar, and the description goes far past them: it discloses the 400-on-mixed-fields refusal, blocking_errors/AMBIGUOUS_UN_VARIANT behavior, withheld lines, null-vs-false semantics for exempt, rate-limit reset_at, and the deterministic-not-legal-advice caveat.

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

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

The purpose is front-loaded, but the body is an unusually long wall of text with overlapping restatements (ID/air-only behavior appears in both the Routing and scope passages, and again in the schema). Much of it earns its place for edge cases, yet the density and repetition make it harder to scan than it needs to be.

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

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

Given the complexity (multi-variant UNs, mixed loads, scope verdicts, air-only IDs) and the rich output schema and annotations, the description still covers the limitations, the envelope fields, and the full edge-case taxonomy. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is already 100%, but the description adds meaning the schema doesn't: the packing_group-equivalence rule, when variant_index is required, the ID-prefix air-only routing, and why basis='gross' yields no points. That is meaningful depth beyond the field 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?

Opens with a specific verb+resource+outcome: 'Calculate ADR 1.1.3.6 small load exemption points for a dangerous-goods load and say whether it qualifies.' It explicitly names the relief route (1.1.3.6) and distinguishes itself from siblings by pointing to adr_lookup and adr_lq_eq_check as the alternative routes.

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

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

States exactly when to use each input form (single substance vs items[]) and that they must never be combined, and names the alternative tools for the data lookup and the LQ/EQ relief routes. The Routing section gives explicit conditions under which lines are counted, withheld or rejected.

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

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

Goes well beyond the read-only/idempotent annotations: discloses pagination shape (total, truncated, next_offset; 50 vs 100 page caps), that no-hit searches error with name suggestions, that 28 Table A scope rows return packing_group null plus not_subject_to_adr/carriage_prohibited, and rate-limit errors carrying reset_at. This is exactly the behavioral context annotations cannot supply.

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

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

Front-loaded and clearly sectioned, but long, and the 'Returns:' block enumerates per-entry fields that are already carried by the output schema, so those sentences do not fully earn their place. The mode-selection and edge-case sentences do earn theirs.

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

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

An output schema exists, so return values need not be re-described; the description nonetheless covers usage modes, error and edge-case behavior, normalization, and a legal-limitations caveat. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is already 100%, so the baseline is 3, but the description adds real meaning on top: the mutual-exclusivity constraint ('exactly ONE of') that the schema does not encode, and the normalization rule ('1203', 'UN1203', 'un 1203' are equivalent) plus leading-zero handling for explosives.

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

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

States a specific verb (look up) and resource (ADR 2025 European dangerous-goods reference data for a substance), and immediately enumerates the returned fields. It also distinguishes itself from siblings like adr_lq_eq_check and adr_exemption_calculator by naming them and their distinct roles.

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

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

Explicitly states the selection rule: 'Provide exactly ONE of: un_number ... search ... or hazard_class', with the semantics of each mode (exact lookup returning all packing-group variants, partial name match, class-wide listing). The Related line routes the agent to the right alternative tools for adjacent tasks.

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

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

Annotations only declare read-only, idempotent, closed-world; the description adds far more: mass-vs-volume dimension mismatches return 'inconclusive' rather than pass/fail, multi-variant UN disambiguation rules and equivalence, withholding behavior in mixed batches, not_subject / not_permitted statuses, field-name validation errors, and a rate-limit error carrying reset_at. This is a rich behavioral disclosure well beyond the structured fields.

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

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

It is front-loaded and organized into Behavior / Returns / Limitations / Related paragraphs, but the ambiguity paragraph is extremely dense and clause-heavy, and much of the long Returns listing duplicates the output schema that already exists. Several conditions are restated (overall_status never reading 'qualifies' appears for both inconclusive and withheld cases), which costs 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?

For a tool with this much edge-case behavior, the description is complete: it covers statuses, ambiguity handling, scope exclusions (not subject to ADR, carriage prohibited), rate limits, the response envelope, and explicit limitations. An output schema exists, so the return-value coverage is generous rather than required, but nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further: it clarifies that quantity is per INNER packaging (not the whole load), spells out the unit families (ml/L liquids, g/kg solids), and explains packing_group vs variant_index disambiguation including when a packing group suffices via equivalent variants. It stops short of adding anything on inner_packaging_qty beyond what the schema says.

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

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

The opening sentence gives a specific verb and resource — 'Check whether dangerous goods qualify for ADR Limited Quantity (LQ, ADR 3.4) or Excepted Quantity (EQ, ADR 3.5) relief' — with the exact ADR chapters named. It also distinguishes itself from siblings by explaining what LQ and EQ actually compare, so an agent can tell it apart from adr_lookup without opening the schema.

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

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

It states the required inputs (mode plus 1-20 items), which mode does what, and routes elsewhere via 'Related: adr_lookup (the per-substance LQ/EQ values + variant_index), adr_exemption_calculator (the 1.1.3.6 load-points route instead).' The alternatives are named with the condition that selects them, though it never explicitly says when LQ relief checking is the wrong route versus those siblings beyond the limitations note.

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

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

Goes well beyond the annotations (which only declare read-only/idempotent/non-destructive) by disclosing fuzzy-match confidence semantics, the FUZZY_BEST_MATCH advisory, no-name fallback behavior with a concrete example, pagination row counts, full-vs-summary behavior, and a rate limit whose error carries reset_at. It also flags the provenance caveat.

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

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

Front-loads purpose and is organized into Behavior, Returns, Limitations and Related blocks. It is on the long side, and the 'Returns' enumeration of per-airline fields is largely redundant given a structured output schema exists, but the content is dense and each block earns its place.

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

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

For an 8-parameter, no-required-params lookup with annotations and an output schema, the description covers purpose, invocation mode, fuzzy/fallback semantics, pagination, rate limiting, and a data-provenance limitation. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains that query is a ranked fuzzy search while iata/icao/prefix/country are exact filters, and defines the AWB prefix concept (first 3 digits of an air waybill, e.g. 176 = Emirates). The 'Provide ONE parameter' constraint is also semantics not 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?

States a specific verb and resource (search airlines) plus the exact search dimensions (name, IATA, ICAO, AWB prefix, country) and the dataset size. It also names sibling tools it is NOT (airport_lookup searches airports, not carriers), so an agent can distinguish it without opening a schema.

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

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

Explicitly tells the agent to provide ONE parameter and splits usage semantics into fuzzy (query) vs exact (iata/icao/prefix/country), which is actionable guidance. The Related section names the alternative tools and their distinct scopes, though it stops short of a full when-not-this-tool-rule.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description goes well beyond them: exact code hits return one record, ambiguous searches return ranked candidates with confidence (basis match_quality), unknown codes raise a not-found error, and rate limiting surfaces reset_at. Error and rate-limit semantics are exactly the kind of context annotations cannot carry.

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?

Well front-loaded: identification and input rule come first, behavior and limitations after. The 'Returns:' block enumerates fields that the output schema already defines, which is mild redundancy, but the sectioning keeps it scannable and no sentence is 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?

For a reference-lookup tool with annotations and an output schema present, this covers the remaining agent-facing questions: input exclusivity, matching/ranking behavior, error shape, rate-limit signaling, and a data-accuracy limitation. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the per-parameter syntax is already documented and the baseline is 3. The description adds real semantics the schema does not encode: the exactly-one-of constraint among iata/icao/query and the fact that type narrows rather than selects. It stops short of explaining tie-breaking or match-quality thresholds.

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

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

States a specific verb and resource (look up an airport) plus the three accepted lookup keys and the dataset scope (85,555 airports). It explicitly differentiates itself from nearby siblings: nearest_airport (coordinate-based), airline_lookup (carriers/AWB, not airports), unlocode_lookup (general transport locations). An agent can route correctly without opening any schema.

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

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

Gives an explicit selection rule — 'Provide ONE of iata, icao, or query' — and explains what the optional type filter does. The Related section names each alternative and the condition that selects it, including a clear when-not for airline_lookup and unlocode_lookup.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description layers on substantial extra behavior: deterministic identity of outputs, totals computed from unrounded figures and rounded only for display, exact conversion factors, validation errors that name the offending parameter, and rate-limit errors carrying reset_at. This is exactly the added context that annotations cannot supply.

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

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

The purpose is front-loaded in the first sentence, followed by behavior, returns and related tools in a clean progression with no filler. The Returns paragraph partially duplicates the output schema's field list, which is the only notable redundancy in an otherwise tight definition.

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

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

For a deterministic calculator with a validation surface, the definition covers inputs, arithmetic semantics, rounding, error and rate-limit behavior, and even the snake_case vs camelCase field-naming difference between the package and the hosted endpoint. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so all four parameters (pieces plus the three dimensions) are already documented in the schema with types, bounds and examples. The description restates the linear scaling relationship (pieces x per-piece CBM) but adds no new syntax or format guidance beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource — 'Calculate cubic metres (CBM) for a shipment from per-piece dimensions' — and immediately defines the domain term. The Related section names the adjacent calculators, so an agent can tell this apart from chargeable_weight_calculator, consignment_calculator and unit_converter without opening any schema.

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

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

The Related line routes the agent with explicit conditions: use chargeable_weight_calculator for air billing weight from the same dims, consignment_calculator for multi-line totals, unit_converter for single conversions, shipment_summary for composite analysis. This is clear alternative mapping, though it stops short of stating an explicit 'do not use this when…' exclusion.

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

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

Annotations already establish readOnly/idempotent/non-destructive, so the bar is easily cleared, and the description still adds substantial behavior: deterministic output, unrounded-then-rounded-for-display math with a worked example (10,000 pcs = 250 kg), the meaning of basis values, explicit input-validation error behavior, and rate-limit reset_at semantics. This is exactly the context annotations cannot carry.

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

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

Front-loaded with the core formula and then the per-piece/total and rounding caveats, so the important content is not buried. It is dense but generally earns its length; the extended field-by-field return listing and camelCase/snake_case mapping notes are somewhat redundant given a full output schema exists, which keeps it from a 5.

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

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

For a calculator with 6 parameters and an output schema, every decision an agent must make — which weight governs, per-piece vs total inputs, divisor choice, unit basis, error and rate-limit behavior — is covered. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description earns above baseline by disambiguating the trickiest parameter relationship — dimensions are per piece while gross_weight_kg is the TOTAL across all pieces — a distinction that is easy to get wrong even with the schema text present.

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

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

States a specific verb and resource ('Calculate air freight chargeable weight') and immediately defines the computation (greater of actual gross weight and volumetric weight). It squarely distinguishes itself from siblings by naming cbm_calculator, consignment_calculator and uld_lookup with a short role for each.

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 scopes itself to air mode and states the exclusion — sea W/M is handled by consignment_calculator with mode=sea — so an agent knows both when to use it and when to route elsewhere. The Related line adds a secondary routing map for volume-only and multi-line cases.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial non-schema context: deterministic behavior, advisory-only flags that never assert compliance or permission, invalid lines erroring with the offending field name, and a rate limit whose error carries reset_at. This is exactly the extra behavioral layer the annotations don't cover.

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?

Dense but well-organized and front-loaded: purpose first, then inputs, behavior, returns, limitations, related tools. The Returns paragraph partly duplicates the output schema, which is mild waste, but the rest earns its place.

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

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

Given a nested schema, full schema coverage, annotations, and an output schema, the description covers everything an agent still needs: alternative parameter forms, defaults, error semantics, rate-limit behavior, and the advisory/non-compliance boundary.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds genuine meaning beyond the schema: it marks lines[] as canonical vs. legacy items[], states the air divisor default of 6000 and that container_number/awb_number drive a check-digit flag. This helps an agent choose the right parameter shape rather than merely restating the schema.

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

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

States a specific verb (calculate) and the precise outputs (CBM, LDM, volumetric weight, mode-specific chargeable figure) for multi-item mixed consignments. It explicitly distinguishes itself from the single-figure siblings (cbm_calculator, chargeable_weight_calculator, ldm_calculator) and shipment_summary.

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

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

Gives clear input guidance (provide mode plus lines[] or legacy items[]) and names the related tools with the differentiated conditions in parentheses, e.g. shipment_summary 'adds vehicle/container suggestion and duty estimates'. It stops short of an explicit 'use X instead when Y' rule, but the routing 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?

Annotations already declare read-only, idempotent, non-destructive and closed-world, so the safety profile is covered — but the description goes further and adds real behavioral context: per-record provenance, case-insensitive/ISO-code/short-form type parsing, the unknown-type error with slug suggestions, the rate limit and its reset_at behavior, and the request envelope (confidence, _source, citation, provenance_status).

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

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

Purpose, coverage and the primary type/omit choice are front-loaded, and the prose is dense but organised. It is however long for a reference lookup, and parts of it restate schema-level semantics already documented per-parameter (full, limit/offset paging, item weight behavior).

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 9-parameter, zero-required reference tool with an output schema, everything needed to call and interpret it is present: the type slug format and error recovery, the list vs single-record modes with pagination and truncation flags, the fit-calculation method and its documented limitations, and the manufacturer-typical-specs caveat.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not carry: 'type' is accepted in any letter case, as the ISO size-type code ('45G1') or the short name form ('40HC'), and an unknown value errors with the valid slugs plus the closest match. It also clarifies that item dims together trigger the fit calculation and weight caps it by max payload.

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

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

The opening sentence states a specific verb and resource ('Get ISO shipping-container specifications, with optional load-fit maths') and immediately scopes coverage to 10 named container types. It is clearly distinguishable from siblings like uld_lookup (air freight) and validate (check digits), which the description also names explicitly.

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

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

It gives explicit mode-selection rules: provide 'type' for one record, omit it to list all 10, add item dimensions to get a load-fit calculation. The 'Related' block routes the agent away from this tool for adjacent jobs (validate for ISO 6346 numbers, cbm/consignment calculators for cargo volume filled, uld_lookup for the air equivalent), with the distinguishing condition stated for each.

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 cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds substantial context beyond them: deterministic output, empty running already baked into the fleet-average factor, unknown mode/region returning available:false rather than a fabricated factor, rate limiting with reset_at, and basis substitution behavior. This is genuinely rich behavioral disclosure.

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

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

Front-loaded with the formula and required inputs, then progressively adds caveats and limitations. It is dense and long, but nearly every sentence carries actionable content (mass_basis warning, no-routing constraint, empty-running note, rate-limit behavior). Not padded, though it could be trimmed marginally.

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 calculator with an output schema, the description still covers the return envelope (wtw/ttw, factor edition, tonne-km, _source), confidence, limitations, and failure modes. Nothing an agent needs to call or interpret it correctly is missing.

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

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

Schema coverage is 100% and enum values are documented, so the schema carries much of the load. The description still adds real meaning beyond it: mass must be ACTUAL GROSS MASS not chargeable/volumetric weight, distance must be supplied by the caller, and region maps to specific authorities (uk=DEFRA, us=EPA, fr=ADEME). Slightly above 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?

States a specific verb (estimate) and resource (freight transport GHG emissions in kgCO2e), gives the exact formula and the ISO 14083 / GLEC v3.2 standard. It also explicitly distinguishes itself from cbm_calculator / ldm_calculator / chargeable_weight_calculator, so an agent can pick it without opening any schema.

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

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

Explicitly states when to use it (mass + distance + mode, with optional sub_mode/region/basis), when NOT to expect anything (this tool does NOT route, geocode, or compute distances), and names the sibling tools it is distinct from. The alternative-selection rule is fully stated.

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

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

Goes well beyond the annotations by disclosing that this is a static local response with no API call, never rate-limited, no account or payment action, and that the user opens the URL in a browser. That is exactly the operational context an agent needs before surfacing a link.

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

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

Front-loaded with the action and payload, then cleanly segmented into 'Behavior' and 'Returns' blocks. No sentence is wasted and each label earns its space.

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

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

Given a single optional enum param, full annotations, and an output schema, nothing an agent needs is missing. The behavioral disclosures close the remaining gaps even though the output schema already covers return values.

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

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

Schema coverage is 100% and the single 'tier' enum is fully documented in the schema, so the description carries little added burden. Mentioning 'the Pro plan' reinforces the only supported tier, but adds no syntax or constraint beyond the schema — baseline 3.

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

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

States a specific verb and resource ('Return the FreightUtils pricing page URL') plus the payload details (Pro plan limit and price). The purpose is instantly clear and, since every sibling is a calculator or lookup, an agent can place it without further digging.

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

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

Explicitly names the trigger: 'Use when the user asks about FreightUtils plans, pricing or API limits.' It does not name a when-not condition or an alternative tool, but no sibling overlaps with pricing, so 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 read-only/idempotent, but the description adds substantial behavior: the two-stage search with HMRC fallback, the medium-confidence signaling (matched_via, citation), count 0 as a valid answer, and rate-limit behavior with reset_at. This goes well beyond structured fields.

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

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

Long but well-structured with labeled sections (Behavior, Returns, Limitations, Related) and the core instruction front-loaded. Every sentence carries information, though the Returns paragraph partially duplicates what the output schema already provides, costing a little economy.

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 needn't be restated, yet the description also covers fallback semantics, confidence, rate limits, and scope limits. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains that query searches HS 2022 descriptions first then falls back to HMRC everyday names, that code returns the hierarchy, and that section browses a section. Minor gating detail (min 2 chars, dots/spaces) is echoed from the schema but the fallback semantics are genuinely additive.

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

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

States a precise verb+resource with scope: 'Search 6,940 WCO Harmonized System (HS 2022) commodity codes — the 6-digit international customs classification layer.' It clearly separates itself from siblings like uk_duty_calculator (duty/VAT) and ics2_check (ENS description quality). An agent can identify the tool without opening the schema.

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

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

Explicitly instructs 'Provide ONE of: query, code, or section' and describes the condition for each mode. The Related block names alternatives with their distinct purposes, and the Limitations section states when the tool is NOT appropriate (national tariff lines, duty rates).

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 establish the safe read profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), and the description adds substantial context beyond them: deterministic term matching, per-term notes distinguishing standalone vs embedded stop-words, the crucial caveat that clean=true does not mean acceptance, absence of a binary verdict, and rate limits with a reset_at field. This is exactly the behavioral disclosure a caller needs.

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

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

Front-loaded with the core action and dense with useful detail; the behavior, caveat and limitations sections are well ordered. It loses a point for the awkward 'Returns:' paragraph that names '_source' twice and restates return values already covered by the output schema.

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

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

For a single-parameter reference checker with annotations and an output schema, every dimension an agent needs is covered: purpose, scope, caveats, rate-limit behavior, legal limitations, and sibling relationships. The redundant return enumeration is harmless rather than a gap.

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

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

There is one parameter at 100% schema description coverage, and the schema already provides the example ('gifts' flagged vs 'wooden toys for retail' specific), so the baseline is 3. The description adds only the semantic framing that this maps to ENS data element 18 05 000 000 and how flagged terms are interpreted, not new syntactic or format guidance.

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

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

States a specific verb and resource ('Check a goods description against the official EU ICS2 stop-words list') and immediately scopes it to the ENS goods-description field. It explicitly separates itself from siblings like hs_code_lookup ('a different field of the ENS') and uk_duty_calculator ('unrelated to ENS screening'). An agent can select this without opening any schema.

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

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

Gives explicit when-to-use ('checking a goods description before an ENS is filed') and when-not ('not an ENS filing, not a customs-compliance determination, not legal advice'). It also names two related siblings and states why they are different fields, so alternative selection 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?

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial behavior beyond them: an unknown code errors with the valid code list, DAT resolves to its successor DPU (ICC), and the tool is rate-limited with a reset_at timestamp in the error. This is exactly the operational context an agent cannot infer from structured fields.

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

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

It is long, but segmented into scannable blocks (guidance, Returns, Limitations, Related) and front-loads the core purpose. Almost every sentence carries distinct information (category split, list shape, error behavior), though the density is near the upper limit for a reference lookup.

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 5-param, 0-required reference tool with an output schema and full annotation coverage, the description supplies the category model, list-vs-record behavior, error semantics and authoritative-source caveat. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning on top by explaining the code-only vs category-only vs neither combinations, what a summary list row contains, and that a single-record call always returns the full record — useful semantics beyond the per-field schema text.

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+resource ('Look up the 11 Incoterms 2020 trade rules') and immediately scopes it by naming which rules belong to each transport category. It names the sibling tools it relates to (uk_duty_calculator, shipment_summary), so an agent can position it among the 25 lookup/calculator siblings without opening the schema.

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

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

Explicitly enumerates the invocation patterns: pass 'code' for one rule, 'category' for a filtered list, or neither to list all 11. It also states when full:true applies and points to related tools, leaving no ambiguity about when to pick this tool versus alternatives.

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?

Far exceeds what the annotations provide: it discloses the fits logic (length, floor positions, and payload only when weight_kg is given), how stackable/stack_height divide the footprint, when payload_checked is false, how floor positions are derived versus record counts, and that rate limits return reset_at. None of this is derivable from readOnlyHint/idempotentHint.

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

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

Purpose and input contract are front-loaded, but the middle is a dense semicolon-chained paragraph, and the 'Returns:' block enumerates fields the output schema already declares — wasted space given an output schema exists. Every claim is relevant, yet it could be trimmed considerably.

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 9-parameter calculator with edge cases (stacking, payload limits, deprecated presets, floor-position basis, rate limits), the description covers the behavior an agent needs and the annotations cover safety. Nothing essential is missing.

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

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

With 100% schema coverage the baseline is 3, but the description adds genuine meaning the schema doesn't: 'Euro and UK pallets count as their own floor positions', that weight_kg is what activates the payload side of fits, and the LDM convention behind the vehicle presets. It stops short of a full per-parameter treatment, so not a 5.

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

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

States a specific verb and resource ('Calculate loading metres (LDM) for European road freight') and immediately defines the concept ('how much trailer length a pallet load occupies'), so an agent knows exactly what this computes. It also names its siblings (vehicle_lookup, pallet_fitting_calculator, consignment_calculator), separating this tool from adjacent calculators.

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

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

Gives a clear input contract ('Provide a pallet preset OR custom length_mm + width_mm — omitting both errors with a usage hint') and routes to alternatives via the Related line. It doesn't state an explicit when-not-to-use case, but the sibling routing is concrete enough that an agent can pick correctly.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, and the description adds substantial context beyond them: deterministic distance sort, how confidence is computed (proximity + airport size, with caps on closed/heliport/seaplane), a rate-limit behavior including reset_at semantics, input-only/no-logging guarantee, and the reference-data limitation.

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

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

Front-loaded with the core operation, then organized into Behavior/Returns/Limitations/Related sections that each earn their place. Slight redundancy in restating decimal-degree latitude/longitude already covered by the schema.

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

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

An output schema exists, yet the description still usefully names the return shape (count, results[] with distance_km, confidence, _source, citation envelope), and covers limitations, rate limits, and sibling routing for a 5-param tool. Nothing material is missing.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds value: it states max_results range and default (1-50, default 10), gives a type-filter example ('large_airport only'), and clarifies coordinates are input-only. It stops short of documenting radius_km semantics beyond what the schema says.

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

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

States a specific verb+resource ('Find the airports nearest to a caller-provided latitude/longitude') with the sorting method (haversine distance) and result field (distance_km). It explicitly distinguishes itself from airport_lookup (exact code or name, no distance) and unlocode_lookup.

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

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

Explicit when-not guidance: 'does NOT geocode place names and does NOT compute routes — pass coordinates you already hold.' It names both relevant alternatives with the condition that selects them (airport_lookup for exact code/name, unlocode_lookup for named transport-location search), plus a limitation about verifying 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?

Annotations already establish the safe read-only, idempotent profile, and the description adds substantial context beyond that: deterministic aligned-row packing with no interlocked/mixed-orientation modelling, weight_limited semantics for payload capping in whole layers, the pallet_deck_height_cm default of 15, error behaviour naming the offending parameter, and rate-limit errors carrying reset_at. This is exactly the value-add structured fields cannot carry.

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

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

The definition is long, but it is clearly front-loaded and partitioned into Behavior / Returns / Limitations / Related labels, and nearly every sentence carries distinct operational information. A minor amount of the Returns enumeration could be trimmed since an output schema exists, but nothing is padding.

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

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

For a 10-parameter computational tool with an output schema, the description covers behaviour, defaults, error and rate-limit handling, output field semantics, a camelCase/snake_case caveat, and explicit modelling limitations. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains that allow_rotation triggers a 90-degree attempt, that weight_limited reports payload capping below geometric fit, and how whole-layer counting and the part-layer note work. It also clarifies the output naming convention (snake_case here vs camelCase on the hosted endpoint).

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

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

The opening sentence states a specific verb and resource ('Calculate how many identical boxes fit on a pallet') and enumerates the exact outputs (boxes per layer, layer count, totals, utilisation, weight capping). The Related line explicitly distinguishes it from ldm_calculator, vehicle_lookup and container_lookup, so an agent can tell it apart from siblings without opening any schema.

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

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

The Related section names three sibling tools and gives each one's distinct scope (pallets into trailer length, pallet capacity per vehicle, pallets into containers), which is strong routing context. It stops short of explicit when-to-use/when-not-to-use phrasing, so it is clear context rather than full conditional guidance.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description layers substantial behavior on top: the deterministic normalize-match-rank pipeline, the exact ranking precedence with inspectable rank_basis, zero candidates being a valid non-error result, failed container check digits returning valid:false instead of being dropped, and rate-limit errors carrying reset_at. It also candidly states the limit of what a match asserts. This is well beyond what structured fields convey.

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

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

The purpose is front-loaded and the 'Behavior'/'Limitations'/'Related' labeling makes it scannable. However, the dedicated 'Returns:' paragraph enumerates fields that the output schema already defines, making a ~100-word block functionally redundant, and the example token list is repeated verbatim in the schema. It is informative but over-long for a one-parameter tool.

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

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

For a single-input meta-resolver the description covers everything an agent needs: input constraints, the grammars dispatched, ranking and ambiguity semantics, failure and rate-limit handling, and the explicit scope limits of v1. Return values are also present in the output schema, so nothing material is missing.

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

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

Schema coverage is 100% and the schema already supplies the example tokens, so the baseline is 3. The description adds real value by enumerating the thirteen grammars that consume the parameter and stating the ambiguity contract (colliding grammars return multiple ranked candidates, never a silent guess), but it contributes no syntax or format detail the schema lacks.

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

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

Opens with a precise verb+resource+scope: 'Resolve an arbitrary freight identifier — one opaque string in, typed and cited candidates out.' It explicitly positions itself apart from siblings by naming the lookups it resolves into (adr_lookup, airline_lookup, airport_lookup, unlocode_lookup, etc.) and by stating the discriminating condition (use when you do NOT know the identifier's kind).

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

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

Gives an explicit when-to-use trigger ('when you hold one identifier-ish token ... and do not know what kind of identifier it is'), explicit when-NOT boundaries ('SINGLE-TOKEN resolution, not free-text extraction — pass one identifier, not a manifest line'; SCAC/BIC not covered), and enumerates the alternative lookup tools. The routing decision against siblings is inferable without opening any schema.

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 read-only/idempotent/non-destructive/closed-world, yet the description adds substantial context beyond them: which engines it invokes versus computes inline, the 2.40 m LDM divisor and non-stacked default, palletSpaces-as-floor-positions vs palletRows, how the vehicle and container are chosen, that unrunnable sections surface in warnings, that unknown field names are refused with a tool error listing accepted ones, and rate-limit behavior carrying reset_at.

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

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

Front-loaded with the value proposition and organized into input / behavior / returns / limitations / related blocks. It is long and repeats some schema content (notably adr_quantity), but nearly every sentence conveys a distinct behavioral fact rather than filler.

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

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

For a composite with nested items, enums, output schema and multiple downstream engines, the description covers the full picture: required inputs, per-section enablement rules, fallback-to-warnings behavior, engine provenance, and an explicit 'planning summary, not a quotation or compliance determination' limitation. Redundant return-value detail is harmless given the output schema exists.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds meaning the schema does not: dims in cm and weight in kg are PER ITEM (quantity multiplies), adr_quantity is a per-LINE total distinct from gross weight, and origin/destination/incoterm 'refine the duty leg'. It restates some schema text, but the cross-field clarifications earn the extra point.

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

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

Opens with a concrete verb+resource ('Composite shipment analysis in one call') and enumerates exactly what it computes (volume, weights, LDM, volumetric weight, revenue tonnes, DG presence, duty). The Related section explicitly distinguishes this composite from the single-purpose siblings (ldm_calculator, adr_lookup, uk_duty_calculator are the engines it calls; cbm_calculator etc. are the inline equivalents). An agent can route correctly without opening another schema.

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

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

Tells the agent exactly what to supply (mode + items[]) and what optional inputs unlock which sections (hs_code + customs_value enable duty; un_number enables DG). The Related list clarifies which tools this one wraps versus duplicates, but it stops short of an explicit 'use X instead when Y' rule versus consignment_calculator, which is the closest sibling.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds substantial value beyond them: live per-request rate fetching, refusal of 6-/8-digit codes with declarable_codes returned, refusal of non-ISO origins, origin-dependent measures surfacing as warnings, and a rate-limit error carrying reset_at. This is exactly the behavioral disclosure an agent needs.

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

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

Front-loaded with purpose and formula, then behavior, returns, limitations, and related tools in a scannable structure. It is dense but nearly every sentence carries distinct operational information; the snake_case/camelCase endpoint note is the one mildly tangential addition.

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?

A complex, revenue-relevant calculation tool with a live external dependency, and the description covers computation, failure modes, rate limiting, return envelope semantics, and explicit limitations (excise, quotas, anti-dumping, not a customs ruling). Combined with the output schema and annotations, nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents all six parameters and the baseline is 3. The description goes further by explaining the CIF composition formula (customs_value + freight_cost + insurance_cost), the duty and VAT arithmetic, and the role of incoterm as documenting which costs are already included.

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

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

States a specific verb+resource (estimate UK import duty and VAT for a commodity code) and immediately distinguishes itself from its siblings by naming hs_code_lookup and incoterms_lookup and their roles. An agent knows exactly what this tool computes and when it is the right choice.

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

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

Gives a clear workflow prerequisite (hs_code_lookup to find the 6-digit code first) and marks which parameters are required vs optional refinements. It never states an explicit when-not-to-use case (e.g. duty-only or VAT-only scenarios), so it falls short of a clean 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?

Well past what the annotations cover (readOnly/idempotent/openWorld=false): it discloses error behavior (unknown type errors with closest codes), rate-limit semantics with reset_at, pagination mechanics (full/limit/offset, five per page), envelope shape, a PROVENANCE_PENDING advisory, and contested-data warnings (PGA tare band, tare confirmed by no non-tertiary source on 13 of 16 records). This is unusually rich behavioral context for a read tool.

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

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

Purpose, behavior, returns and limitations are front-loaded and reasonably ordered, but the middle section on second-agent coverage, stamp withdrawal and publisher-level corroboration runs very long relative to what an agent needs to select and invoke the tool. The operational warnings earn their place; the verification narrative is over-expanded.

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

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

With an output schema present the description needn't explain return values, yet it still notes the envelope, casing differences between local and hosted endpoints, and pallet records lacking internal dimensions with a pointer to max_build_up_height_cm. Nothing needed to call it correctly or interpret the data cautiously is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning beyond the schema by noting that type also accepts the record's own informal name ("LD3" → AKE), which the schema does not state. It otherwise restates the code/slug examples and omit-to-list behavior already documented 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 opening states a specific verb and resource (look up air-cargo ULD specifications) and quantifies scope (16 types across lower-deck containers, main-deck pallets, temperature-controlled units). It explicitly separates itself from siblings like container_lookup (the sea-freight equivalent) and chargeable_weight_calculator, so an agent can route without opening schemas.

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

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

It gives concrete selection mechanics (pass a type code/slug to get one record, omit to list all 16, use category/deck to filter) and a Related list that frames alternatives by function. It stops short of stating explicit when-not-to-use conditions or task-level triggers for choosing this over, say, ldm_calculator or pallet_fitting_calculator.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: deterministic behavior on exact legal factors, refusal behavior with accepted units listed by category, the response naming both units and formula, and rate limiting with reset_at in the error. This is exactly the extra behavioral detail annotations cannot convey.

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

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

Front-loaded with the core purpose and unit categories, then behavior, then returns, then related tools. Dense but well-organized; the ton-definition note is mildly extraneous but supports the stated exact-factor behavior, so little is wasted.

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

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

Though an output schema exists and return values needn't be spelled out, the description still summarizes the envelope, and it covers behavior, refusals, rate limits, and alternative tools. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 100% and both enum params are documented, so the baseline is 3. The description adds genuine meaning beyond the schema by giving the actual conversion formulas for chargeable_kg (IATA 6,000 divisor) and freight_tonnes (W/M), and clarifying the ton variants.

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

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

States a specific verb (Convert) and the exact resource scope (freight/logistics units across weight, volume, length, plus two freight-specific targets). It names sibling tools cbm_calculator and chargeable_weight_calculator, so an agent can distinguish it without opening any schema.

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

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

Explicitly routes the agent: the 'Related' line gives cbm_calculator as the step for dimensions-to-volume and chargeable_weight_calculator for proper air billing with pieces/custom divisor. It also states hard usage constraints (freight targets only FROM cbm, cross-dimension and negative values refused), covering both when to use and when not.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description still adds substantive behavior: exact hits are provenance-based while fuzzy name hits carry confidence via envelope basis match_quality, an unknown code produces a not-found error, and rate limiting surfaces reset_at (UTC reset time). The 116,232-record fixed list also corroborates openWorldHint=false rather than contradicting it.

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

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

Front-loaded with purpose and code format, then clearly sectioned into invocation, behavior, returns and limitations. It is dense and mostly earns its length, but the 'Returns:' block partially duplicates the existing output schema and could be trimmed.

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 5-parameter lookup with full schema coverage, annotations and an output schema, this description covers everything an agent needs: what it is, how to call it, error and rate-limit behavior, and the authoritative-source caveat about confirming operational status. Nothing material is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value beyond it: the spaced notation rule ('GB LHR' resolves to GBLHR), the min-2-char query constraint, and the limit default/max. It stops short of explaining how code and query interact when both are supplied, or how country/function_type behave on a mass name match.

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

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

States a specific verb+resource (search the UN/LOCODE transport-location list) and immediately scopes the domain with the code format and concrete examples (GBLHR, NLRTM). It explicitly differentiates itself from the two closest siblings, airport_lookup and nearest_airport, so an agent can route without opening schemas.

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

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

Gives the two invocation modes (exact `code` vs. `query` name search) and the narrowing filters (country, function_type, limit). The 'Related:' line names both alternatives and the condition that selects each (airport-specific records with ICAO codes; coordinate-based airport search), which is the explicit routing an agent needs.

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 establish read-only, idempotent, non-destructive and closed-world, so the bar is lower; the description still adds substantial behavioral context: deterministic check-digit arithmetic, per-identifier reporting fields, the ambiguous-airline-prefix resolution rule (airline null plus airline_candidates[] rather than a guess), empty-result behavior, rate limiting with reset_at, and the FreightUtils v1 response envelope.

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

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

Front-loaded with purpose and modes, then behavior, returns, limitations and related tools in clearly labelled blocks. It is long, but nearly every sentence carries non-redundant information for a multi-mode validator, so it is dense rather than padded.

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

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

For a three-parameter validator with an output schema, the description covers everything an agent needs: mode selection, enum values, resolution edge cases, empty results, rate-limit signaling, and the structural-only limitation. The existence of an output schema means return-value detail is a bonus rather than a requirement, and it is supplied anyway.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters, the enum, the 'value requires type' constraint and examples. The description restates the mode split but adds no syntax or semantic detail beyond what the schema provides; baseline 3 is appropriate.

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

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

States a specific verb (validate/parse) and resource (freight identifiers), enumerating the three standards (ISO 6346, IATA modulus-7, IMO) it applies. It also explicitly distinguishes itself from siblings by noting container_lookup is about container TYPE specs rather than numbers, and airline_lookup is the prefix dataset used for resolution.

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 lays out the two mutually exclusive modes (text=<arbitrary string> to scan, or value=<identifier> + type=<enum> for one) with a concrete example for each. It names the related tools and the condition that separates them, and adds a clear when-not statement ('STRUCTURAL ONLY — not a registry or tracking lookup').

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

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

Annotations already cover read-only/idempotent/non-destructive, but the description goes well beyond them: unknown-slug error behavior (returns valid list plus closest slugs), provenance on single records, list-row shape with total/truncated/next_offset/detail_hint, five-per-page pagination under full:true, and a rate-limit error carrying reset_at. That is unusually rich operational 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?

Long but front-loaded and sectioned (capabilities, behavior, returns, limitations, related), with no filler sentences. It is on the verbose side for a lookup tool, and the camelCase/snake_case envelope note could be shorter, but each block carries usable information.

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

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

With an output schema present the description need not explain return values, yet it still covers error paths, pagination, rate limits, envelope field naming differences between the package and hosted endpoint, and an explicit limitations paragraph on provenance and plated weights. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds cross-parameter meaning the schema documents only piecewise: that a single-record call always returns the full record regardless of full, and that the default page size shifts to five when full:true. It also explains the slug/list/filter interplay as a workflow.

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

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

States a specific verb+resource ('look up road-freight vehicle and trailer specifications') and enumerates the 17 vehicle types covered, including EU articulated trailers, US dry vans, rigids and vans. This is clearly distinguishable from siblings such as container_lookup or uld_lookup, which cover different equipment domains.

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

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

Gives explicit selection rules: supply a slug for one record, omit it to list all 17, and use category/region to filter the list. It also names three related tools (ldm_calculator, pallet_fitting_calculator, consignment_calculator) as downstream calculations, though it stops short of saying when NOT to use this tool.

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