FreightUtils MCP Server

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

Annotations already declare read, idempotent, non-destructive and closed-world, and the description adds substantial behavior beyond them: determinism, verdict semantics (fail vs not_applicable vs conditional vs insufficient_data), the rule that reliefs that do not apply never change status, missing_inputs population, edition precedence and the 2027-06-30 transition, a rate limit with reset_at in UTC, and receipt storage with vs without an API key. This is unusually complete behavioral disclosure for a check tool.

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

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

The opening summary is well front-loaded and the paragraphs are organized by check, but the description is a dense wall of run-on clauses and repeatedly restates the return shape under 'Returns:' even though an output schema exists, which is redundant bulk. Rules like not_applicable vs fail are explained more than once (behaviour paragraph and limitations). Content largely earns its place, but tightness is poor.

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 this complex (7 params, nested objects, output schema, multilingual rule citation) nothing material is left unsaid: editions and their legal timeline, the full limitation list (mark vs packaging kind, IBC not read, Part 9 approval not assessed, 7.5.7 not assessed, no legal advice), and identifier guidance (fu_id, resolve_reference). Return values are correctly deferred to the output schema despite the redundant recap.

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 86%, yet the description adds genuine meaning the schema does not carry: journey.date as the default as_of with contradiction refusal, max_mass_t as the 8.1.4.1 band / 3.4.13 threshold, un_mark as the printed 6.1.3.1 mark parsed by sub-paragraph (a)-(g) and held against packing group (X/Y/Z), inner_packaging.regime as the trigger for LQ/EQ exclusion from the 1.1.3.6 total, and icao_limited_quantity as ID-line-only and exempt from document counting.

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 names a specific verb+resource+scope ('One call on the consignment object for the ADR picture of a road load') and then enumerates the exact checks performed (1.1.3.6, LQ/EQ, tunnel, document entry, 7.5.2 mixed loading, 5.3, 8.1, 8.2, 6.1.3.1). The 'Related' line explicitly separates it from adr_exemption_calculator, adr_lq_eq_check and adr_lookup, so an agent can route 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?

It states the context of use (a road load consignment, full ADR picture) and routes narrower needs to siblings ('adr_exemption_calculator (the 1.1.3.6 check alone), adr_lq_eq_check (LQ / EQ alone), adr_lookup (a row's columns)'), plus conditions under which the answer degrades to conditional when vehicle/crew inputs are absent. What is missing is an explicit statement of when NOT to call it (e.g. a single-line quantity question), and the routing information sits at the very end rather than up front.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, but the description adds substantial behavior: a deterministic calculation over reference data, rate limiting with reset_at, NOT_FOUND blocking errors, refusal of unknown fields by name with 400s, exempt/total_points staying null rather than defaulting to false, and the deliberate conservative treatment of mixed loads. This is well beyond what the annotations 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?

There is a strong front-loaded opening sentence, but the body sprawls across many long paragraphs and the "Returns:" section enumerates output fields that the existing output schema already defines, so those sentences do not earn their place. The ADR 2027 / transitional-measure material is relevant but repeated in several places (basis, Editions, transitional_1_6_1_61/1_1_1), making the text far larger than an agent needs to select and call the 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, deeply nested 11-parameter calculator with an output schema, the description covers every ambiguity an agent would hit: multi-variant UN resolution, withheld lines and null verdicts, ID-prefixed air-only lines, gross-vs-net basis, edition/as_of selection and transitional measures, plus limitations. Nothing material to a correct call 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 cross-parameter meaning the schema cannot: un_number/quantity and items[] are mutually exclusive and every single-substance field sent beside items[] is refused by name, un_number also accepts an ID-prefixed air-only number, quantity 0 means not carried, and packing_group can resolve by equivalence when rows agree. Dense enough to raise it 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?

Opens with a specific verb and resource: "Calculate ADR 1.1.3.6 'small load' exemption points for a dangerous-goods load and say whether it qualifies." It is clearly distinguishable from siblings, naming adr_lookup for per-substance data and adr_lq_eq_check for the LQ/EQ relief routes instead of 1.1.3.6.

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

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

Explicit when-to-use and when-not: 1.1.3.6 relieves goods carried in packages only, not bulk or tanks; category 0 substances can never use the exemption; LQ/EQ loads belong to adr_lq_eq_check; ambiguous UNs require adr_lookup for variant_index. Alternative routes and exclusions are stated outright rather than inferred.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, yet the description still adds real behaviour: paging is never silently truncated (total, truncated, next_offset), rate limits carry reset_at, a miss errors with closest-name suggestions, 28 scope-remark rows return packing_group null plus not_subject_to_adr or carriage_prohibited. The verification_status taxonomy and edition applicability window are disclosed beyond anything in 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?

Labels (Behavior, Returns, Editions, Limitations, Related, Identifiers) give useful structure and scope is front-loaded, but the returns sentence is a single enormous run-on enumerating 20 columns and then re-enumerating the resolved_codes payload. Substantial content duplicates the output schema, which exists, and the verification_status list of seven values is inline bloat.

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, multi-mode lookup with an output schema, every decision an agent must make is covered: which mode, how to page, what defaults apply, how editions resolve, what happens on misses and rate limits, and the legal/verification caveats. The remaining verbosity is a conciseness issue, not a completeness one.

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 earns credit by adding semantics the schema only partly carries — un_number normalisation with echo of the correction, explosives keeping the leading zero, include_codes defaults differing per lookup mode, and edition-beats-as_of precedence with the 2027-06-30 transition. It largely restates the schema's own enum and precedence text rather than adding new meaning, which caps it below 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 — "Look up the full European road dangerous-goods (ADR 2025) Table A entry for a substance" — and immediately scopes it (all 20 columns, 2,939 entries, UNECE source). The three lookup modes (un_number, search, hazard_class) plus the Related list make it distinguishable from adr_lq_eq_check, adr_exemption_calculator and consignment_calculator 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?

Gives explicit mode selection ("Provide exactly ONE of: un_number ... search ... or hazard_class") and routes downstream work to siblings with conditions ("adr_lq_eq_check (checks quantities against the LQ/EQ values returned here)"). Gaps: the un_numbers batch parameter is documented in the returns paragraph but omitted from the "exactly ONE of" rule, and no guidance is given on when to prefer url-based code resolution over include_codes full.

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 adds behavior those annotations cannot express: deterministic reference check, withheld items in mixed batches, overall_status never reading "qualifies" while anything is withheld, blocking_errors + human_review_required on fully ambiguous batches, explicit refusal of unrecognized fields, not_subject handling for "NOT SUBJECT TO ADR" rows, and rate-limit errors carrying reset_at. Nothing here contradicts 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?

Purpose is front-loaded and the labeled paragraphs (Behavior, Editions, Limitations, Related, Identifiers) aid scanning, but the prose is dense with nested parentheticals and run-on sentences that are hard to parse in one pass. The "Returns:" paragraph substantially restates the output schema, and the Identifiers/fu_id paragraph is largely irrelevant to deciding whether and how to call this 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 4-parameter batch tool with an output schema, everything an agent needs is present: eligibility rules, ambiguity protocol, edition timeline, scope exclusions, failure modes, rate limits, and the disclaimer that results are not legal advice. If anything it over-supplies detail, but 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 would be 3, but the description adds cross-parameter meaning the schema cannot: quantity is "per INNER packaging, not the whole load," a mass quantity against a volume limit returns inconclusive rather than a verdict, and packing_group resolves by equivalence when rows agree while variant_index is required only when they disagree. Some text does restate schema content (mode values, edition precedence), which keeps it short of 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?

The opening sentence names 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," and the Related section explicitly separates this from adr_lookup (raw per-substance values) and adr_exemption_calculator (the 1.1.3.6 load-points route). An agent can pick this tool over its two nearest 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?

It states which mode to send ("lq" or "eq"), what the caller must supply, and when the tool is the wrong instrument ("a quantity-threshold check only — LQ/EQ relief also requires packaging, marking and documentation conformity that this tool does not assess"). It also routes to alternatives by name for the two adjacent use cases, so both the when and the when-not are covered.

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

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

Goes well past the annotations: pagination shape (summary rows, 25 per page, total/truncated/next_offset), the asymmetry between list answers and full holder records for iata/icao/prefix, fuzzy fallback behavior with a concrete example ('Emirats' → Emirates), and rate-limit semantics (limit error carries reset_at in UTC). The 'stale/no warranty' caveat (provenance_status pending verification) is exactly the kind of risk context 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 and labeled (Behavior, Returns, Limitations, Related, Identifiers), which helps scanning. However, the long 'Returns' paragraph enumerates output fields one by one even though an output schema exists, so a sizeable portion of the text is redundant with structured data rather than adding to it.

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

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

Covers everything an agent needs for a 9-parameter, zero-required lookup: how to choose the one parameter, what each answer shape looks like, paging, rate limits, provenance risk, and identifier resolution via resolve_reference. Nothing material is missing given the annotations and output schema already in place.

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: the fuzzy-vs-exact split between query and the code filters, why prefix is three digits, and that a query without a name falls back to closest names. That is interpretive guidance the schema patterns alone do not provide.

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 and resource plus dataset scale ('Search 6,356 airlines by name, IATA code, ICAO code, AWB prefix, or country') and immediately explains what an AWB prefix is. It explicitly separates itself from airport_lookup ('searches AIRPORTS, not carriers') and validate, so an agent can pick 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?

Gives a clear routing rule for its own parameters ('Provide ONE parameter: query is ranked fuzzy... iata / icao / prefix / country are exact filters') and names two alternatives with their triggering conditions (airport_lookup for airports, validate for check-digit validation). It stops short of stating when not to use the tool at all, but the alternative routing is explicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered upstream; the description still adds real value with ranked-candidate ordering, confidence/match_quality reporting, and not-found vs rate-limit error behavior including reset_at. It stops short of describing result ordering guarantees for the batch path or how partial failures are surfaced beyond 'each with its own status' in the schema.

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

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

Front-loaded with the identifier forms and then cleanly partitioned into Behavior, Returns, Limitations, Related, and Identifiers sections, so an agent can skim. It is longer than strictly necessary, and the Returns/Identifiers material partly duplicates what the output schema and resolve_reference already imply.

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 definition still summarizes the envelope shape, source attribution, and data provenance, plus a sensible 'not for navigation' limitation and rate-limit reset semantics. The one substantive hole is the batch `codes` workflow: with five parameters and an explicit 'Send alone' constraint, leaving it out of the narrative is a real 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%, so the baseline is 3 and the schema already documents formats and the type enum. The description adds useful semantics for query ambiguity (ranked candidates, exact codes first, then larger airports) and for the type filter narrowing results, but it silently omits the `codes` batch parameter, which is the one parameter whose exclusivity rule ('Send alone') an agent could easily violate.

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 the exact verb and resource (look up an airport) and enumerates the three accepted identifier forms with concrete examples. It explicitly separates itself from the most confusable siblings, noting that nearest_airport finds airports FROM a coordinate and that airline_lookup searches carriers rather than airports.

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

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

Explicitly says to provide ONE of iata, icao, or query, and lists three related tools with the condition that selects each, which is strong routing guidance. However it never mentions the batch `codes` parameter, so an agent reading only the description would not know a multi-code lookup mode exists at all.

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 readOnly/idempotent/non-destructive/closed-world, yet the description adds material behavior beyond them: determinism, that totals are computed from unrounded figures and rounded only for display, that invalid dimensions produce a validation error naming the parameter, and that rate-limit errors carry reset_at in UTC. It also notes snake_case vs the hosted endpoint's camelCase, which is a real behavioral difference an agent must handle.

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

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

Front-loaded with purpose, then Behavior, Returns and Related — a predictable structure with no filler sentences. The Returns paragraph is the weakest part: with an output schema present, enumerating result fields is largely redundant, and the camelCase aside is useful but sits oddly in that block.

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

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

For a 4-parameter deterministic calculator, the description covers inputs (per-piece dims, pieces), computation and rounding rules, error behavior, rate limits, and sibling alternatives, while an output schema exists to cover return values. Nothing an agent needs to call this correctly and interpret failures appears to be 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 meaning beyond the field descriptions: dimensions are per-piece, pieces multiplies into the total ("total volume = pieces x per-piece CBM"), and rounding is deferred to display. It does not restate units per parameter, but the multiplication semantics and per-piece scoping 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?

Opens with a specific verb+resource: "Calculate cubic metres (CBM) for a shipment from per-piece dimensions." It defines what CBM is and scopes the input as per-piece dimensions, and the Related section names the closely related siblings (chargeable_weight_calculator, consignment_calculator, unit_converter, shipment_summary) with one-phrase differentiators, so an agent can separate this from ldm_calculator or consignment_calculator 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?

The Related block gives clear routing context by describing what each alternative does ("air billing weight from the same dims", "multi-line totals", "single conversions"), which implies selection conditions. There are no explicit when-not or exclusion statements (e.g. "use ldm_calculator instead when you need load metres/freight-tonne by volume-to-deck"), so guidance is clear but not fully enumerated.

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 this a safe, idempotent, non-destructive read, and the description still adds substantial behavior: deterministic output, the per-piece vs total weight convention, unrounded-then-displayed rounding with a worked 10,000-piece example, the meaning of "basis", named-parameter validation errors, and rate limiting that returns reset_at in UTC. 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?

The core definition is front-loaded in the first sentence, which is good, but the Returns paragraph is long and largely restates fields the output schema already declares, including a snake_case/camelCase mapping note of marginal decision value. Dense reference prose rather than a crisp brief.

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 full schema coverage and an output schema, everything an agent needs to call it correctly and interpret the result is present: units, divisor choice, per-piece vs total semantics, rounding, error and rate-limit behavior, and sibling routing.

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 real domain meaning: the divisor's IATA 6,000 default versus the 5,000 used by express integrators, and the 1 CBM = 166.67 kg equivalence. It also reinforces the pieces/gross_weight_kg asymmetry, which the schema states but the description ties to a concrete 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?

"Calculate air freight chargeable weight — the greater of actual gross weight and volumetric weight" gives a specific verb, resource, and the governing business rule, plus the exact formula and divisor conventions. It is unmistakably distinct from siblings like cbm_calculator (volume only) and ldm_calculator.

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

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

It names an explicit exclusion (air mode only) and routes sea W/M traffic to consignment_calculator with mode=sea, while the Related line positions cbm_calculator, consignment_calculator, and uld_lookup by their distinct roles. An agent can pick the correct tool 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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial behavior beyond them: determinism, that flags are advisory only and never assert compliance, the specific flag categories (implausible density, mode/option mismatch, ADR 2025 dangerous-goods, container/AWB check digits), that invalid lines error naming the offending field, and that rate-limit errors carry reset_at. That is materially more than the annotations 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 and the remaining paragraphs are labelled by function (inputs, behavior, returns, editions, limitations, related), so scanning is easy. It is long and the Returns paragraph restates fields an output schema already enumerates, which is mild redundancy, but 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 high-complexity tool with nested objects, 7 parameters and an output schema, the definition covers input shape, defaults, error behavior, edition selection, advisory-flag semantics and limits. The explicit non-regulatory disclaimer is important for a dangerous-goods-adjacent calculator and is stated clearly.

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 carries the parameter detail and a baseline 3 is the floor. The description still adds non-obvious meaning: the air_volumetric_divisor default of 6000 and that it only affects air, that items[] is legacy cm/kg, and the edition-vs-as_of precedence rule including the ADR 2025/2027 transition window. It does not document the nested consignment object that the schema also exposes.

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 plus resource: calculate per-line and grand totals for a multi-item mixed consignment, enumerating the concrete outputs (CBM, LDM, volumetric weight, mode-specific chargeable figure). The 'Related' line explicitly separates it from cbm_calculator / chargeable_weight_calculator / ldm_calculator by calling those 'single-figure versions', so an agent can distinguish intent 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?

Declares the default mode (road) and the accepted input shapes, stating lines[] is canonical and items[] is a deprecated legacy alias with cm/kg units. The Related section routes the agent to shipment_summary for vehicle/container suggestions and adr_lookup for flagged UN numbers. It stops short of an explicit 'use this instead of X when Y' exclusion rule, so it is strong context rather than full when/when-not guidance.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), but the description adds substantial behaviour the annotations do not: case-insensitive and ISO size-type code input parsing, an error path that returns valid slugs plus a closest match, rate limiting with reset_at, and a candid limitation that fit maths is geometric best-effort without load distribution, securing or mixed cargo. Provenance caveats and the snake_case vs camelCase envelope difference between the package and the hosted endpoint are also disclosed.

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 deliberately structured into Behaviour / Returns / Limitations / Related / Identifiers sections, with the core purpose front-loaded in the first sentence. The weak spot is the Returns paragraph, which partially restates field names the output schema already documents and includes an endpoint-naming aside that is not needed to invoke the 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 9-parameter reference tool with computed load-fit, pagination, error and rate-limit paths, the description covers everything an agent needs: input forms, branch conditions, error recovery, limitations and disambiguation from siblings. Since an output schema exists, the brief return summary is sufficient rather than required.

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 nonetheless adds real meaning — slug examples, the fact that 'type' accepts any letter case and ISO codes like "45G1" or "40HC", and that item_length_cm is only meaningful together with width/height and a type. Pagination semantics for 'full: true' (five per page) go slightly beyond the schema's default note.

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

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

The description opens with a specific verb and resource ("Get ISO shipping-container specifications") and immediately delimits scope by enumerating the 10 container types covered. It also names its nearest siblings (validate, cbm_calculator, consignment_calculator, uld_lookup) with one-line distinctions, so an agent can separate this from every adjacent tool.

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 branch conditions: supply 'type' for a single record, omit it to list all 10, add 'full: true' for full records, and add item dimensions only when a load-fit calculation is wanted. It also tells the agent when to go elsewhere — validate for container numbers (not specs), cbm_calculator/consignment_calculator for cargo volume, uld_lookup for the air-freight analogue.

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

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

Beyond the annotations (readOnly/idempotent/closed-world), the description discloses determinism given the same factor edition, that the fleet-average factor already includes empty running, that sea/air factors are low-representativeness defaults, that unknown mode/sub_mode/region returns available:false rather than a fabricated factor, and that rate-limit errors carry reset_at. That is substantial behavior beyond structured fields, though it stops short of stating latency or caching behavior.

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

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

Front-loaded with the formula and required inputs, which is good, but it is long (~350 words) and re-enumerates schema facts already given (mode list, region=DEFRA/EPA/ADEME, basis default), and the closing 'Identifiers' paragraph about fu_id/fu_version_id/resolve_reference is tangential to calling this tool. Dense but not tight.

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

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

For a 7-parameter, enum-heavy, read-only calculator with full schema coverage, an output schema, and rich annotations, nothing an agent needs is missing: inputs, defaults, failure modes, return envelope (result, confidence, _source, citation), and the reference-only limitation are all covered.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above that by adding a real semantic trap — 'pass ACTUAL GROSS MASS, not chargeable/volumetric weight (a common air-freight mistake — see mass_basis in the result)' — and by tying basis/region choices to their default and authority mapping. It does repeat several enum values verbatim from the schema, which caps it below 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 ('Estimate freight transport greenhouse-gas emissions (kgCO2e) for a shipment leg') and gives the governing standard (ISO 14083:2023 / GLEC v3.2) plus the formula. It explicitly differentiates itself from cbm_calculator / ldm_calculator / chargeable_weight_calculator as 'estimates its CO2e' vs 'size or bill a shipment', so an agent can route between siblings 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?

Names the required inputs, the optional selectors, and a hard precondition: 'Distance must be provided — this tool does NOT route, geocode, or compute distances', which prevents the most likely misuse. It also warns against a specific alternative behavior ('do NOT add your own empty-return leg') and names the sibling tools it is not, giving both when-to-use and when-not-to-use 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 annotations already declare readOnly, idempotent and closed-world, but the description goes further: it says the response is static and local, never rate-limited, and involves no account or payment action, and that the user opens the URL in a browser. That directly prevents the agent from treating this as a checkout or subscription step, which the name might otherwise imply.

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

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

Three short sections — trigger, behavior, returns — front-loaded with the core purpose. Every sentence carries information an agent needs; 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?

An output schema exists, yet the description still enumerates the returned fields, so completeness is not in doubt. For a single-parameter, static, local tool, nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100% and the single 'tier' parameter is documented as an enum restricted to 'pro'. The description only implicitly covers it by describing the Pro plan, adding no syntax or format detail beyond the schema, so the baseline 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 gives a concrete verb and resource: it returns the FreightUtils pricing page URL together with the Pro plan's request limit and price. That is specific and distinguishable from every sibling, which are calculators and lookups. It loses a point only because the tool name ('get_subscribe_link') and title point at subscribing/pricing while no sibling overlaps, so there is mild naming friction the description has to correct.

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 an explicit trigger: use when the user asks about FreightUtils plans, pricing or API limits. No sibling covers that intent, so no alternative needs naming, and the boundary is clear.

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, yet the description adds substantial behavior beyond them: the two-stage search and fallback, medium-confidence signaling via matched_via, the instruction to confirm a citation, that count 0 with empty results[] is still valid, and that rate-limit errors carry reset_at. Limitations (6-digit only, no national tariff lines or duty rates, indicative not a binding ruling) 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?

Front-loaded with the core action, then cleanly sectioned with bolded labels (Behavior, Returns, Limitations, Related, Identifiers) that make it scannable. The "Returns:" block partly duplicates the existing output schema and the fu_id paragraph is tangential, but neither is padding enough to obscure selection.

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 lookuppable tool with full annotations, 100% schema coverage, and an output schema, an agent has everything needed: what it searches, how to invoke each mode, how to read confidence, what an empty result means, and which sibling to use next. The only minor omission is the batch `codes` route in the description, which the schema itself fully documents.

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 3 is the baseline, but the description adds real meaning: code formats are interchangeable ("8471.30" is 847130) and return the code plus its hierarchy, section is Roman numeral I–XXI to browse, and query has a specific documented fallback chain. The `codes` batch parameter is never mentioned in the description, which keeps this from 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+resource with exact scope: "Search 6,940 WCO Harmonized System (HS 2022) commodity codes — the 6-digit international customs classification layer," and even explains the 2/4/6-digit hierarchy, so an agent knows precisely what is and is not covered.

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

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

Explicit routing guidance: "Provide ONE of: query … code … or section," plus the fallback rule (query searched first, HMRC index second) and named alternatives — uk_duty_calculator for duty/VAT, ics2_check called out as "a different check entirely," resolve_reference for fu_id. The one gap is that the mutually-exclusive enumeration omits the `codes` batch parameter, so an agent reading only the description could think batch lookup is unsupported.

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 readOnly/idempotent annotations: it discloses deterministic term matching, the meaning of the two note types (standalone = automatic rejection vs embedded = make more specific), the crucial caveat that clean=true does not guarantee acceptance, that no binary verdict is returned, and that rate-limit errors carry reset_at. Limitations (not a filing, not legal advice, non-exhaustive list) are spelled out.

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

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

The purpose and behavior sections are front-loaded and dense with useful information, but the "Returns:" block restates what the existing output schema already provides, and the closing "Identifiers:" paragraph about fu_id and resolve_reference is boilerplate that does not earn its place for a single-parameter read-only checker.

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 and full annotation coverage, the remaining burden is behavioral framing, and the description covers matching semantics, result caveats, rate limiting, scope limitations, and sibling relationships. Nothing an agent needs to call this correctly or interpret the result 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 a little by framing the value as the ENS goods-description field and giving an explicit "Pass description=<goods description>" invocation pattern. It does not add length, language, or formatting constraints on the string, so it stops short of 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 precise verb and resource: "Check a goods description against the official EU ICS2 stop-words list," and pins it to data element 18 05 000 000 of the ENS. It also names two siblings (hs_code_lookup, uk_duty_calculator) and explains they cover different fields, 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 a clear usage context ("Intended for checking a goods description before an ENS is filed") and distinguishes itself from the two related tools it is most likely to be confused with. It stops short of explicit exclusions or a routing rule such as "if you need X, use Y instead," so it is not quite a 5.

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

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

Annotations already cover read-only, idempotent, non-destructive and closed-world, and the description still adds real behavioral detail: unknown codes error with the valid code list, DAT resolves to its successor DPU, and rate-limit errors carry reset_at in UTC. What it does not cover is whether a code lookup is case-sensitive or how confidence/_source should be interpreted, so it stops just short of a 5.

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

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

Front-loaded with purpose and scope, then call shapes, then behavior and returns; each block is doing distinct work. It is on the dense side and the trailing 'Identifiers' section is somewhat tangential for a lookup call, but no sentence is pure 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 5-parameter reference lookup with an output schema and full annotation coverage, the description supplies everything an agent needs: valid inputs, filtering modes, error behaviors, the response envelope, and a binding-text limitation. The caveat that the ICC publication prevails is exactly the kind of scope limit an agent should surface.

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 cross-parameter semantics the schema cannot express: 'full' applies only to list calls while a single-record call always returns the full record, and lists default to every summary row versus 5 with full: true. It also notes that responses carry total and next_offset, tying offset/limit to pagination behavior.

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 and resource ('Look up the 11 Incoterms 2020 trade rules') and enumerates the exact scope, including which 7 rules are any-mode and which 4 are sea-only. It distinguishes the three call shapes (single code, category filter, no filter) so an agent can tell it apart from siblings like hs_code_lookup or uk_duty_calculator.

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 logic: 'Provide code for one rule, category ... for a filtered list, or neither to list all 11.' It also names the related tools and the specific relationship (uk_duty_calculator accepts an incoterm when composing the CIF value; shipment_summary for composite analysis), which routes the agent 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?

Goes well past the annotations: declares determinism, explains that stackable=true with stack_height 2 or 3 divides the floor footprint, enumerates the three independent fit limits (length, floor positions, payload) and says each failure is named in warnings[] with its numbers. It also discloses the payload-check opt-in (payload_checked is false without weight_kg) and a rate-limit reset_at, none of which the readOnly/idempotent hints 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-loads the purpose and the input rule well, and the Returns/Related block is a logical ordering. But the middle paragraph is a dense wall of capitalized claims (LENGTH, FLOOR POSITIONS, PAYLOAD) with nested basis/record_count caveats, and the long Returns enumeration largely duplicates the supplied output schema, so several sentences do not earn their place.

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

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

For a zero-required-parameter calculator with 9 params, an output schema and full annotation coverage, nothing an agent needs in order to call it correctly is missing: inputs, fallbacks, limit semantics, warnings and rate limiting are all addressed. The only redundancy is restating return fields that the output schema already defines, which is surplus rather than a gap.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning the schema does not: the preset-vs-custom mutual requirement, the footprint effect of stackable + stack_height, and that weight_kg is what triggers payload checking. It does not explain how quantity interacts with stacking or spell out custom vehicle_length_m usage beyond the schema's own note, so it stops short of 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 unit ('1 LDM = 1 linear metre of a 2.4m-wide trailer; a standard artic is 13.6 LDM'), so an agent knows exactly what is being computed. The Related section names the three nearest siblings with a one-phrase role for each, which distinguishes this tool from pallet_fitting_calculator and consignment_calculator without opening their 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 a concrete input precondition: 'Provide a pallet preset OR custom length_mm + width_mm — omitting both errors with a usage hint', plus signposting to vehicle_lookup for trailer specs and consignment_calculator for mixed lines. It reads as clear routing context, but never states an explicit 'do not use this when…' condition, so the choice against consignment_calculator is left partly to inference.

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

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

Beyond the annotations (which only declare read-only/idempotent/non-destructive), it discloses the default ranking rule (scheduled service + IATA only, never heliports or closed fields), how confidence is computed and capped, the rate-limit failure mode with reset_at, and that coordinates are input only with no storage or logging. These are substantive operational details an agent could not get from 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?

Front-loaded with the core purpose, then cleanly partitioned into Behavior, Returns, Limitations and Related sections. There is mild redundancy in restating the heliport/closed-field exclusion twice and the Returns list partly duplicates the output schema, but no sentence is truly wasted.

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

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

For a 6-parameter read-only lookup with an output schema, everything an agent needs is present: input units and ranges, filtering defaults, determinism, error behavior, confidence interpretation, and reference-data caveats. The fu_id/citation note covers identifier traceability even though the return shape itself is carried by the output schema.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds real meaning: the interplay between include_all and type ('ranks every type except closed fields, and type filters on that type') and the default scheduled-service/IATA scoping are not obvious from the schema alone. It doesn't add anything on radius_km or max_results beyond the schema, which keeps it short of 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 ('Find the airports nearest to a caller-provided latitude/longitude') plus the ranking method (haversine, distance_km per result) and corpus size (86,248 OurAirports records). It is immediately distinguishable from airport_lookup, which is described as an exact code/name lookup with no distance.

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 defines the preconditions ('Provide latitude and longitude'), the exclusions ('does NOT geocode place names and does NOT compute routes — pass coordinates you already hold'), and names the correct sibling for the alternative task ('airport_lookup (exact code or name lookup, no distance)'). Nothing about when to choose this tool is left to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behaviour, so the bar is lower, yet the description still adds real substance: deterministic aligned-row packing with no interlocked or mixed-orientation modelling, how weight_limited caps at whole layers, the 15cm deck default, error behaviour on non-positive dimensions, and rate-limit errors carrying reset_at. This is well beyond what the annotations 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 'What it does / Behavior / Returns / Limitations / Related' structure is front-loaded and scannable, but the Returns block re-lists a dozen field names even though an output schema exists, which is largely redundant. The camelCase-versus-snake_case note does earn its place, but the paragraph around it is dense and could be tightened.

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 ten-parameter geometric calculator with a rich output schema, the definition covers the packing model, defaults, failure and rate-limit behaviour, utilisation definitions that could otherwise be misread (footprint vs envelope), and sibling routing. Nothing an agent needs to invoke it correctly appears to be 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 meaning the schema does not: allow_rotation is described behaviourally ('trying 90-degree rotation when allowed'), pallet_deck_height_cm's default is restated with its effect on usable height, and invalid dimensions are said to error naming the offending 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?

Opens with a specific verb and resource: 'Calculate how many identical boxes fit on a pallet', then enumerates the outputs (boxes per layer, layer count, totals, utilisation, weight capping). The 'Related' line names ldm_calculator, vehicle_lookup and container_lookup with their distinct roles, so an agent can separate this from neighbouring 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?

The Related section gives clear routing context by stating what each sibling does (pallets into trailer length, pallet capacity per vehicle, pallets into containers) and the Limitations section sets expectations about when results are only theoretical. It stops short of explicit when-not-to-use guidance against every alternative, such as cbm_calculator or chargeable_weight_calculator, which are near neighbours not addressed.

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 behavior beyond them: deterministic normalization rules, full-grammar matching, the ranking order (record-hit > verification status > dataset prior > stable tiebreak), the fact that zero candidates is a valid result rather than an error, that a failed container check digit returns valid:false instead of dropping the candidate, and that rate-limit errors carry reset_at. This is exactly the extra context 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?

Well front-loaded — purpose, parameter, behavior, returns, limitations, related — and nearly every sentence carries information an agent needs. It is still dense and long for a one-parameter tool, with heavy parenthetical enumerations of ADR Table A subcodes and grammars that could be compressed without losing meaning.

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 an output schema existing, the description still summarizes the response envelope (query, normalized, count, candidates[] with entity_type, rank_basis, canonical_url, api_url, citation) so the agent knows what it is getting. Combined with explicit limitations (no SCAC/BIC, match does not assert shipment existence) and the fu: identifier note, nothing needed 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 coverage is 100%, so the baseline is 3, but the description adds real meaning: it clarifies the single-token 32-character shape for ordinary identifiers versus the up-to-200-character fu: form, and explains that an fu: identifier resolves to exactly one record or none. That goes beyond the schema's example list, though it does not enumerate every grammar's input format.

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 — 'Resolve an arbitrary freight identifier' — and immediately frames the exact contract: 'one opaque string in, typed and cited candidates out.' It distinguishes itself from the sibling lookup tools by positioning itself as the disambiguation entry point that feeds adr_lookup, airline_lookup, airport_lookup, and the rest.

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 condition: 'Use when you hold one identifier-ish token ... and do not know what kind of identifier it is,' with concrete examples. It also states when-not-to-use ('v1 is SINGLE-TOKEN resolution, not free-text extraction — pass one identifier, not a manifest line') and names the downstream tools it resolves into.

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 beyond the readOnly/idempotent annotations, it discloses the delegation to ldm_calculator, adr_lookup and uk_duty_calculator, the 2.40 m loading-metre divisor and the 'no stackable flag means NOT stacked' convention, the smallest-fit vehicle/container selection logic and what utilisationBasis refers to. It also covers failure behavior: sections that cannot run degrade into warnings rather than failing, unknown field names are refused with an error listing accepted ones, and rate-limit errors carry 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?

The purpose is correctly front-loaded, but the body is a wall of multi-clause sentences with deeply nested parentheticals (the vehicle-fit sentence in particular) that take real effort to parse. Detail such as 'a 7.5t rigid holds 15 Euro pallets on the floor' and the duplicated adr_quantity explanation pull weight that the schema or a reference doc could carry.

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 composite with nested objects, delegation to three engines, editable ADR editions and partial-failure semantics, nothing an agent needs to call it correctly is missing: units, per-item vs per-line scope, edition precedence, warning behavior, error shapes and limitations are all present. The Returns block is partly redundant against the output schema, but the camelCase 'legacy shape' note is a genuinely useful addition.

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

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

Schema coverage is 100%, so the baseline is 3, and the description still earns above baseline by stressing the traps: weight and customs_value are PER ITEM while adr_quantity is the TOTAL for the line, and edition overrides as_of with origin/destination and incoterm refining only the duty leg. Some of this restates schema text near-verbatim, and the large nested consignment object is left entirely to its schema description, so it stops short of 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?

The opening sentence names the specific outputs (CBM volume, gross and chargeable weight, road LDM with pallet spaces and vehicle suggestion, volumetric weight, revenue tonnes with container suggestion, dangerous-goods presence, UK duty) and the mode/items inputs that drive them. The Related section explicitly contrasts it with consignment_calculator and the single-purpose calculators, so an agent can place it among 25 siblings 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?

It gives clear invocation context ('Provide mode ... and items[]', with units and per-item vs per-line distinctions) and explains in Related that the three engines are what it calls while cbm_calculator, chargeable_weight_calculator and ldm_calculator are single-purpose equivalents of its inline arithmetic. What it never states is an explicit routing rule such as 'use cbm_calculator alone when you only need volume' — the choice is inferable but not spelled out.

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: live per-request rate fetch, refusal behavior for short codes with declarable_codes returned, ISO-3166 validation of origin, unresolved origin-dependent measures surfacing in warnings, and rate limiting with reset_at. It also enumerates the returned monetary fields. Minor tension: live remote fetching sits awkwardly with openWorldHint=false, though that hint is usually read as 'no arbitrary external entities', so this is a nuance rather than a 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?

Front-loaded with the purpose and inputs, then behavior, returns, limitations and related tools in a clean order. It is longer than needed, and one sentence is off-target for this tool: the FreightUtils v1 / camelCase envelope note references total_cbm, a shipping field this tool does not return.

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 an output schema existing, the description summarizes the key result fields and the as_of timestamp, and covers refusals, rate limits, warnings, and the estimator caveat with a broker/HMRC check. The only gap is batching via lines[], which the schema documents at 100%.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns a 4 by explaining how customs_value, freight_cost and insurance_cost compose CIF and by stressing that origin_country must be an ISO-2 country. It omits the lines[] batch parameter entirely, which is the main alternate input mode, so the prose alone would leave an agent unaware of batching.

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 and resource: 'Estimate UK import duty and VAT for a commodity code using the LIVE GOV.UK Trade Tariff'. It also states the calculation basis (CIF = customs_value + freight + insurance) and names the sibling it does not replace (hs_code_lookup), so an agent can distinguish it from lookup/conversion 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 states the minimum inputs (commodity_code, origin_country, customs_value), which fields are optional refinements, and routes the agent to hs_code_lookup 'find the 6-digit code first' and incoterms_lookup. It also states a hard exclusion (6- or 8-digit codes are refused, never zero-padded) and closes with what it is not (an estimate, not a customs ruling).

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 and idempotent, but the description adds a lot beyond them: unknown-type errors return the closest codes, list responses carry total/truncated/next_offset/detail_hint, full:true pages five at a time, and rate-limit errors carry reset_at. It also discloses the response envelope, the PROVENANCE_PENDING advisory on every response, and the practical trap that pallet records have no internal dimensions and must use max_build_up_height_cm rather than a dimension product.

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 sectioned (Behavior, Returns, Limitations, Related, Identifiers), which helps, but the Limitations block runs on for many sentences about second-agent coverage, withdrawal of stamps, publisher-level corroboration and the PGA weight band. It even instructs the reader to 'read the envelope's provenance_status rather than this sentence', a self-admission that this prose does not earn its place in a tool definition.

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

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

An output schema exists and annotations cover the safety profile, so the description needn't explain return shapes — yet it still supplies error behavior, pagination, rate limiting and the snake_case vs camelCase field-naming difference between the package and hosted endpoint. Nothing an agent needs in order 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 coverage is 100%, so all six parameters are already documented in the schema, which sets the baseline at 3. The description does add real meaning the schema lacks — the type field also accepts a record name and performs a "LD3" → AKE resolution, and it clarifies how offset/limit interact with full:true paging. That is genuine supplementation, but it is spread thin across a long text rather than concentrated on the 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?

Opens with a concrete verb+resource: "Look up air-cargo ULD (Unit Load Device) specifications — 16 types..." and names the three families (lower-deck containers, main-deck pallets, temperature-controlled units). The field inventory (dimensions, tare/max gross, volume, deck, aircraft) makes the output scope unambiguous, and the closing 'Related' line distinguishes it from container_lookup, chargeable_weight_calculator and airline_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?

Gives explicit invocation guidance: type accepts an IATA code, slug, or the record's own name ("LD3" → AKE), omit it to list all 16, and category/deck filter the list. It routes the agent to three siblings with one-phrase differentiators. It stops short of stating when NOT to use it (e.g. when the agent actually wants chargeable weight or a sea container), so it is strong but not a full when/when-not matrix.

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, so the safety profile is covered; the description still adds real value by promising deterministic exact legal factors, describing refusal behavior with accepted units listed by category, and disclosing that rate-limit errors carry reset_at. The response-envelope sentence duplicates what the output schema likely already exposes, which keeps it off a 5.

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

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

Purpose is front-loaded and the Behavior/Returns/Related blocks make it scannable; nearly every sentence carries operational information. The listing of the returned envelope fields (confidence, _source, citation) is the one segment that spends words on something an output schema already conveys.

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 converter with an output schema, annotation coverage, and two enum-constrained fields, the description covers everything an agent needs: legal factors, dimension restrictions, error and refusal semantics, and sibling routing. Nothing material is left for the agent to guess.

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 enums are self-documenting, so the schema carries the baseline. The description still adds meaning the schema cannot: the IATA 6,000 divisor formula for chargeable_kg, the 1 CBM = 1 freight tonne W/M rule, the short/long/metric ton distinctions, and the source restriction on the two freight targets.

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

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

The description opens with a specific verb and resource ("Convert freight and logistics units") and enumerates the exact unit families and members it supports. The closing "Related:" line names cbm_calculator and chargeable_weight_calculator, so an agent can separate this general converter from the specialized calculators 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?

It states the preconditions explicitly: chargeable_kg and freight_tonnes are valid only FROM cbm, and cross-dimension conversions are refused. It also routes the agent to the right alternative in the two cases where a sibling is better — dimensions-to-volume via cbm_calculator, and proper air billing weight with pieces/custom divisor via chargeable_weight_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 read-only, idempotent, non-destructive and closed-world, so the bar is lower; the description still adds real behavior: exact hits are provenance-based, fuzzy hits expose match quality via confidence, unknown codes produce a not-found error, and rate-limit errors carry reset_at. It does not say what a partial fuzzy match does with limit truncation, but the disclosure is well 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?

Front-loaded with purpose and identifier format, then access pattern, behavior, returns, limitations and related tools in labeled form — easy to scan. It is on the long side and the Identifiers paragraph about fu_id/fu_version_id only marginally earns its space given resolve_reference exists as a sibling.

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 six-parameter lookup with an output schema, the description covers everything an agent needs: input modes, code syntax, error and rate-limit behavior, return envelope shape, data-source authority, and a caveat about operational status from an administrative list. Nothing material about invocation or interpretation 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 carries examples and constraints for code, query, country, limit and function_type, so the baseline of 3 applies. The description adds some meaning by explaining the 2-letter country + 3-character location structure of a code and that "GB LHR" resolves to GBLHR, but it leaves `codes` (batch, up to 50, answered in input order) entirely to the schema.

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

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

States a specific verb and resource ("Search 116,086 UN/LOCODE transport locations worldwide") and enumerates the covered record types (ports, airports, rail/road terminals, ICDs, border crossings). The code-format explanation with worked examples (GBLHR, NLRTM) makes the resource unambiguous, and the Related section names the sibling tools it is not.

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 describes the two access modes — "Provide code for an exact record, or query (name search, min 2 chars) optionally narrowed by country and function_type" — and names alternatives with their distinguishing conditions (airport_lookup for ICAO codes, nearest_airport for coordinate search). Only the batch `codes` path is left to the schema, which documents it fully.

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), so credit goes to the added behavior: deterministic arithmetic, per-identifier report fields, empty found[] plus note when nothing matches, and rate-limit errors carrying reset_at. The airline-resolution rule (null plus airline_candidates[] rather than a guessed carrier) is unusually candid. Minor gap: it never mentions the consignment mode's behavior that the schema exposes.

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 mode selection, then clearly labeled Behavior / Returns / Limitations / Related sections, so the agent can skim to what it needs. The parenthetical detail on AWB-prefix ambiguity is slightly long, and the Returns paragraph largely restates what the output schema already carries.

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

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

For a four-parameter tool with a nested object and an output schema, the description covers modes, return shape, error behavior, and scope limits. The only omission is the consignment mode, which the schema itself fully documents, so an agent can still call it correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds genuine semantics beyond the schema: the mutually exclusive text vs value+type modes and what each one scans. It stops short of documenting the 'consignment' type, which appears in the enum and as a nested object parameter but is absent from the description.

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

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

The first sentence names a specific verb (validate/parse) and resource (freight identifiers) and pins each one to its standard: ISO 6346, IATA modulus-7, IMO. It then splits the tool into its two operating modes, so an agent can tell exactly what this does and how it differs from container_lookup or airline_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?

It explicitly states the two call shapes (text=<arbitrary string> for finding everything in a blob vs value + type for a single identifier) and gives a concrete use case ('a booking-email line'). The Limitations section adds the when-not-to-use case: valid check digit is not a registry or tracking lookup, and the Related line routes the agent to the correct siblings for container specs and airline data.

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, but the description adds substantially more: unknown slugs error with the valid list and closest matches, list responses return summary rows with total/truncated/next_offset/detail_hint, full:true pages five records at a time, and rate-limit errors carry reset_at. It also discloses provenance pending verification and the camelCase vs snake_case difference between the local package and the hosted endpoint.

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 is front-loaded and the labeled sections (Behavior, Returns, Limitations, Related, Identifiers) make it scannable. It is dense but slightly overlong, with the slug example and the full/limit/offset paging rules restated from the schema, adding redundancy on a six-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 read-only lookup with a full output schema, the description covers everything an agent needs: record shape, list vs. single behavior, pagination, error and rate-limit semantics, provenance caveats, and the response envelope. Nothing material is left to inference.

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 prose adds real meaning beyond it: the slug example and the omit-to-list behavior, the interaction between full:true and the five-per-page default, and how offset/limit pair with next_offset. Some of this repeats the schema descriptions rather than extending them, which keeps it out of the top band.

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

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

The first sentence names a specific verb and resource (road-freight vehicle and trailer specifications) and enumerates the 17 covered types with concrete detail, so an agent can tell it apart from container_lookup or airline_lookup immediately. It also flags the key scoping axis (slug for one record, omit to list all).

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

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

It explicitly says how to fetch a single record vs. the full list and how category/region narrow the list, and it names three related tools for adjacent jobs (ldm_calculator, pallet_fitting_calculator, consignment_calculator). However, the related tools are listed without an explicit "use X instead when Y" routing statement, so the agent must infer the boundary.

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