FreightUtils MCP Server

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

The annotations declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description adds substantial context beyond these hints. It discloses deterministic arithmetic, rate limiting with 429 and retry_after_seconds, ambiguous UN handling with candidates[] and blocking_errors, and the caveat that it is 'not legal advice'. No contradiction with annotations.

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

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

The description is long but highly structured: purpose in the first line, then input rules, ambiguous-UN behavior, rate limits, return envelope, limitations, and related tools. Every sentence adds needed information, and front-loading the key concept (1.1.3.6 exemption, points threshold) makes it easy to grasp.

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

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

The description covers all key aspects of this complex tool: point calculation formula, 1000-point threshold, category 0 exclusion, multi-variant disambiguation, error/rate-limit behavior, output envelope, and practical limitations. Combined with the rich annotations and output schema, the agent has everything needed to select and invoke the tool appropriately.

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

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

The input schema has 100% coverage, but the description enriches each parameter meaningfully. It explains the precedence of items over single parameters, the kg/L unit convention, how packing_group and variant_index disambiguate multi-variant UNs, and how to obtain variant_index from adr_lookup. This is well beyond what the schema descriptions offer.

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 'Calculate ADR 1.1.3.6 "small load" exemption points' – a specific verb, resource, and regulatory context. It distinguishes itself from siblings by naming adr_lookup (for per-substance data) and adr_lq_eq_check (for LQ/EQ relief routes), making its unique purpose immediately clear.

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

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

The description explicitly says adr_lq_eq_check is for 'the LQ/EQ relief routes instead of 1.1.3.6', providing a direct alternative. It also gives concrete input instructions: 'Provide un_number + quantity for a single substance, or items[] for a mixed load' and explains that 'items takes precedence if both are given'. This is strong practical 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?

While annotations already state readOnlyHint=true, idempotentHint=true, and destructiveHint=false, the description adds substantial behavioral context: read-only reference lookup, response limits (up to 50 for search, 100 for class), error behavior (NOT_FOUND body with retry hint, 429 with retry_after_seconds and Retry-After header), and UN number normalization including leading-zero handling for explosives. No contradiction with annotations.

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

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

The description is organized into clear sections (purpose, usage, behavior, returns, limitations, related tools) and every sentence adds value. Despite being lengthy, it avoids redundancy and front-loads the primary purpose before diving into details.

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

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

The tool has a complex parameter schema and behavior, and the description covers all critical aspects: parameter selection rules, normalization, result caps, error formats, rate limits, return envelope, legal disclaimer, and related tools. It even lists the output fields, which goes beyond what an output schema would require.

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?

Schemas cover 100% of parameters, but the description enriches semantics with behavioral nuances: un_number returns every packing-group variant and is normalized; search is case-insensitive partial match; hazard_class returns all entries in a class/division. It also clarifies the mutual exclusivity constraint and gives examples, which is more than the schema alone provides.

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

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

The description opens with a specific verb ('Look up') and resource ('European road dangerous-goods (ADR 2025) reference data'), enumerating the exact data fields returned (hazard class, packing group, tunnel code, etc.). It further distinguishes itself from sibling tools by naming related tools and their different purposes (e.g., adr_lq_eq_check checks quantities, adr_exemption_calculator computes 1.1.3.6 points).

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

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

The description provides explicit usage instructions: 'Provide exactly ONE of: un_number, search, or hazard_class', and details when each is appropriate (exact UN lookup, partial name match, class/division filter). It also names alternatives and related tools, including get_subscribe_link for rate-limit escalation, making the choice boundaries 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 mark readOnly=true, idempotent=true, destructive=false; the description complements these by explaining rate limits (25 requests/day, 429 with retry_after_seconds), ambiguous UN behavior (blocking_errors + human_review_required instead of a silent verdict), and that it only performs quantity-threshold checks, not full compliance. This adds substantial behavioral context beyond the structured hints and does not contradict them.

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

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

The description is long but each section earns its place: core check, input shape, disambiguation, behavior, return envelope, limitations, related tools. It front-loads the primary purpose, then layers detail, making it navigable for a complex tool. No redundant 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?

With 2 required params, a rich output schema, and safety annotations, the description still goes further by specifying output fields (items[] fields, summary, blocking_errors, human_review_required, citation), the ADR chapter references, rate-limit behavior, and the boundaries of what it verifies. This gives the agent full operational context.

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

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

Even though schema coverage is 100%, the description enriches every parameter: it states that quantity is per inner packaging, unit must match liquid/solid phases, and how packing_group/variant_index disambiguate multi-variant UNs. It also explains inner_packaging_qty's role in EQ mode (per-outer limit) and mode alternatives, so the agent can populate values correctly.

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 action—'Check whether dangerous goods qualify for ADR Limited Quantity (LQ, ADR 3.4) or Excepted Quantity (EQ, ADR 3.5) relief'—which clearly names the resource and scope. It distinguishes itself from siblings by referencing adr_lookup (the per-substance LQ/EQ values) and adr_exemption_calculator (the 1.1.3.6 route), so the agent can pick the right 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 usage instructions ('Provide mode ("lq" or "eq") and 1-20 items...'), clarifies per-inner-packaging semantics, and states when multi-variant UNs require packing_group or variant_index. It also names alternatives in the Related section and lists limitations (packaging/marking/documentation not assessed), so the agent knows when not to rely on it.

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 include readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description goes well beyond this by disclosing the fuzzy match quality reporting mechanism (confidence, FUZZY_BEST_MATCH, NO_MATCH advisories), rate-limiting with 429 retry behavior, and the provenance verification caveat. It also clarifies that no results return a count of 0 rather than an error. No contradiction with annotations.

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

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

The description is longer than many, but it is purposefully structured: lead with core search capability, then parameter semantics, then behavioral details, then returns, then limitations, then related tools. Each sentence carries information—rate limits, advisories, provenance status, and alternatives. It is front-loaded with the primary use case and is dense without bloat, though a slightly more compact format would be possible.

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

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

For a tool with 5 optional parameters, an output schema, rate limiting, and data provenance caveats, the description covers everything an agent needs: input selector rules, match-quality advisories, rate-limit handling, response fields, verification limitations, and sibling tool comparisons. The presence of an output schema removes the need to enumerate full return types, but the description still summarizes the result structure and envelope details usefully.

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

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

The schema already covers parameter formats and descriptions 100%, providing a baseline of 3. The description adds crucial usage semantics: it states the mutual exclusivity of parameters ('Provide ONE parameter'), explains that `query` is a ranked fuzzy search while others are exact filters, and provides a concrete AWB prefix example ('176 = Emirates'). This meaningfully enhances the schema's bare field names and patterns.

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: 'Search 6,357 airlines by name, IATA code, ICAO code, AWB prefix, or country.' It immediately clarifies scope and domains, and explicitly distinguishes itself from sibling tools by noting 'airport_lookup (searches AIRPORTS, not carriers)' and 'validate (checks an AWB number's check digit and names its airline from this dataset).' This is a textbook example of purpose differentiation.

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

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

Provides explicit guidance: 'Provide ONE parameter' and distinguishes the ranked fuzzy search from exact filters. It names alternatives with their contrasting purposes ('airport_lookup' for airports, 'validate' for AWB check digit validation). It also explains expected outcomes for no-hit cases, giving clear when-to-use/when-not-to-use context.

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

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

The description discloses far more than annotations: exact code hits vs. ranked ambiguous search results, confidence/match_quality behavior, not-found errors, rate limits with retry headers, response envelope structure, and data source caveats. It also clearly states 'read-only' aligning with annotations. This fully carries behavioral transparency beyond structured fields.

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

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

The description is long but well-structured into purpose, usage, behavior, returns, limitations, and related tools. Each section adds value and no sentence is redundant. It could be tightened slightly, but the complexity of the tool justifies the length.

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

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

Given the tool's complexity (multiple search modes, output envelope, rate limiting, error behavior), the description is remarkably complete. It covers prerequisites (one-of rule), output semantics, limitations, and related tool disambiguation. The presence of an output schema doesn't reduce the need for the caveats and ambient context provided here.

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?

While schema coverage is 100%, the description adds critical semantic meaning: the mutual exclusivity rule ('Provide ONE of iata, icao, or query'), the meaning of ambiguous query behavior (ranked candidates, exact codes first), and the type filter's narrowing effect. These are not in the schema descriptions and materially help the agent invoke the tool correctly.

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

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

The description states a specific verb ('Look up an airport') with concrete identifier methods (IATA, ICAO, free-text name/city) and explicitly distinguishes from related tools like airline_lookup and unlocode_lookup. The scope ('85,555 airports worldwide') and examples make the purpose unmistakable.

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

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

Provides explicit when-to-use guidance: 'Provide ONE of iata, icao, or query', explains the optional type filter, and names direct alternatives with differentiating details (nearest_airport for coordinate-based lookup, airline_lookup for carriers, unlocode_lookup for general transport locations). This is exemplary usage guidance.

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

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

Behavior is thoroughly disclosed: deterministic output, total volume formula, validation errors naming the parameter, rate limiting with 429 error details (retry_after_seconds and Retry-After header), and backoff/retry guidance. It also lists the exact return fields and the response envelope. This goes well beyond the annotations (readOnlyHint, idempotentHint) and adds critical context without 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?

The description is well-structured into definition, behavior, returns, and related tools. Every sentence carries meaningful information, and the length is justified by the need to cover deterministic behavior, error handling, rate limits, and alternatives. It is front-loaded with the core purpose and avoids redundant filler.

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

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

Given the presence of an output schema and complete input schema, the description still adds necessary context: rate limits with retry handling, validation error behavior, and relationships to sibling tools. It fully equips an agent to decide when to call this tool and what to expect, exceeding the minimum needed for a 4-parameter deterministic calculator.

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

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

The schema already describes all four parameters with 100% coverage, so the baseline is 3. The description adds value by explaining that total volume = pieces x per-piece CBM, clarifying the role of the pieces parameter, and noting that missing/non-positive dimensions trigger a validation message naming the offending parameter. This supplements the schema's basic field descriptions.

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

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

The description opens with 'Calculate cubic metres (CBM) for a shipment from per-piece dimensions,' which is a specific verb+resource statement. It clearly distinguishes itself from sibling tools by naming related calculators (chargeable_weight_calculator, consignment_calculator, unit_converter, shipment_summary) with brief explanations of their differing purposes.

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 explicitly points to alternatives and when they apply: chargeable_weight_calculator for air billing weight, consignment_calculator for multi-line totals, etc. It also states rate limits and directs users to get_subscribe_link for higher limits, which informs when to use an alternative. This is explicit enough to guide tool selection.

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 (readOnlyHint=true, idempotentHint=true, destructiveHint=false), the description discloses deterministic behavior, rounding to 2 decimals, the meaning of 'basis', error behavior for invalid inputs, and the 429 rate-limit response details. This adds substantial context that annotations alone do not provide.

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

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

The description is thorough yet well-organized, with the core purpose in the first sentence, followed by behavior, constraints, errors, and related tools. Every sentence adds value, and the structure is front-loaded with the most critical information. No fluff or repetition.

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

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

Given the tool's complexity (rounding, divisor variants, error handling, rate limits, output envelope), the description covers all essential aspects. It explains the result fields (including basis, ratio, etc.) and points to the output schema context, making it complete for an agent to invoke and interpret results 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 the baseline is 3. The description adds further meaning by explaining the factor parameter as a divisor with IATA vs. express values, and pieces as identical units. It also clarifies rounding behavior that affects interpretation of results. This exceeds baseline without needing to repeat schema descriptions.

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

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

The description opens with a specific verb+resource: 'Calculate air freight chargeable weight — the greater of actual gross weight and volumetric weight', and then explicitly differentiates from sibling tools by noting the sea alternative in consignment_calculator and related volume/equipment tools. This is a model of purpose clarity.

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

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

It clearly states the intended use (air freight) and explicitly excludes sea freight, pointing to consignment_calculator with mode=sea. It also names related tools (cbm_calculator, uld_lookup) for adjacent needs, providing strong when-to-use vs. 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 description discloses that the tool is deterministic, flags are advisory only, it 'never state[s] that a shipment is permitted or compliant', and invalid lines error naming the offending field. It also states limitations (not regulatory/customs/DG compliance advice). These go well beyond the readOnly/idempotent annotations and do not contradict them.

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

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

The description is long but well-structured with distinct labeled sections: input requirements, behavior, returns, limitations, and related tools. Every sentence carries operational value and the first sentence front-loads the core purpose.

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

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

Given the tool's complexity (mode-dependent calculations, multiple input shapes, advisory flags, rate limits), the description covers inputs, outputs, error behavior, limitations, and related tools. The output schema exists, but the description's return summary and related-tool pointers ensure the agent has a complete mental model.

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?

Although schema coverage is 100%, the description adds meaningful semantics: default road mode, default air volumetric divisor (6000), canonical vs legacy input formats, and the check-digit sanity-flag purpose of options.container_number / options.awb_number. This goes far beyond the individual schema property descriptions.

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

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

The description opens with 'Calculate per-line and grand totals for a multi-item mixed consignment' — a specific verb+resource — and enumerates the computed outputs (CBM, loading metres, volumetric weight, mode-specific chargeable). It differentiates itself from siblings by naming cbm_calculator/chargeable_weight_calculator/ldm_calculator as 'single-figure versions'.

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

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

The description explicitly says 'Provide mode (sea | air | road, default road) and either lines[] ... or the legacy flat items[]', telling the agent exactly what to pass. It also covers rate-limit handling (429 with retry_after_seconds, fallback to get_subscribe_link) and names related tools for alternative use cases.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description adds rate limits (25/day with retry_after_seconds), error behavior (unknown type yields valid slug list), best-effort fit calculations, and provenance caveats, giving rich behavioral context.

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

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

The description is well-structured with clear sections (usage, behavior, returns, limitations, related) and every sentence adds value. Despite its length, it is front-loaded with purpose and avoids redundancy.

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

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

The description covers purpose, usage, behavior, return envelope, limitations, rate limits, and alternatives. Since an output schema exists, it need not repeat return field details, but it still mentions key output fields. The only slight gap is the phantom item dimension parameters, but overall it is highly complete.

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

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

The type parameter is well explained with concrete slug examples and list-all behavior, but the description mentions 'Add item dimensions' parameters (item_length_cm, etc.) that are not present in the input schema. This mismatch could mislead an agent into invoking with unsupported parameters, reducing clarity.

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

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

The description clearly states 'Get ISO shipping-container specifications, with optional load-fit maths' and enumerates the 10 container types covered, distinguishing it from siblings like uld_lookup and validate by explicitly naming them in the Related section.

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 instructs when to provide a type slug vs omit it to list all, and names related tools (validate, cbm_calculator, uld_lookup) with their different purposes, providing clear alternatives and exclusions.

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?

Given readOnlyHint/idempotentHint, the description adds substantive context: deterministic results, inclusion of empty running, low representativeness for sea/air, available:false behavior for unknown values, rate-limit and 429 retry semantics, and a caveat that this is not an audited carbon report. No contradiction with annotations.

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

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

Description is long but well-structured with scannable sections (usage, behavior, returns, limitations, related). Every sentence conveys a distinct constraint or fact; no filler. However, the length is somewhat high, so not a perfect 5.

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

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

With extensive context and a rich output schema, the description covers input requirements, edge cases, rate limiting, return envelope, and limitations. It leaves no critical operational gap for an agent selecting or invoking the tool.

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

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

Schema covers all 7 params with descriptions (100%), satisfying the baseline of 3. The description elevates this by clarifying that mass means actual gross mass (not chargeable/volumetric), distance must be user-provided (no routing), and unknown sub_mode/region behavior. This adds cautionary semantics beyond the schema.

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

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

The description opens with a specific verb-object-scope ('Estimate freight transport greenhouse-gas emissions (kgCO2e) for a shipment leg'), includes the calculation formula, and explicitly distinguishes itself from sibling volume/weight calculators. This makes the tool's role unmistakable.

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

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

Provides explicit when-to-use instructions: prerequisites (mass, distance_km, mode), what NOT to do (don't pass chargeable weight, don't add empty-return leg), and names alternatives (cbm_calculator, ldm_calculator, chargeable_weight_calculator) in the 'Related' section. Also mentions rate-limit fallback (get_subscribe_link).

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 communicate readOnly, idempotent, and non-destructive nature. The description adds important behavioral context: 'static local response — no API call, never rate-limited' and instructs agents to hand the URL to the user and 'must NOT attempt to complete the subscription themselves'. These details go beyond what annotations provide.

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

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

The description is concise, using three short paragraphs each with a distinct purpose: purpose/use case, behavior, and return values/agent action. Every sentence adds value, and the most important information is front-loaded.

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

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

For a simple static tool, the description fully covers when to use it, its behavioral characteristics, the return fields, and an explicit agent instruction. The presence of an output schema handles return-value details, so no gaps remain.

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

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

The input schema covers the single optional 'tier' parameter with an enum and description ('only "pro" supported today'), achieving 100% schema coverage. The description adds no additional parameter semantics, so the baseline score of 3 applies.

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

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

The description clearly states 'Get the URL where the user can subscribe to FreightUtils Pro for higher API limits', using a specific verb and resource. It is distinct from all sibling tools, which are calculators or lookups and have no subscription-related purpose.

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

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

The description explicitly gives when-to-use: 'when the user asks how to upgrade or about pricing, or after any other tool errors with a 429 rate_limited body.' It does not mention when-not-to-use, but given there are no sibling subscription tools, no alternative is available. The guidance is clear and actionable.

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 (readOnlyHint, idempotentHint, destructiveHint), the description discloses search behavior (keyword-based, zero-result cases), rate limits (25/day, 429 handling), and limitations (international level only, non-binding). No contradiction with annotations.

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

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

The description is longer but well-structured with dedicated paragraphs for behavior, returns, limitations, and related tools. Every sentence contributes useful information, and the main purpose is front-loaded.

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

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

The description covers the tool's purpose, all input modes, behavioral nuances, output envelope, rate limiting, limitations, and related tools. Given the tool's complexity, the description is comprehensive and self-contained.

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?

Although the schema descriptions are terse, the tool description adds substantial meaning: explains the hierarchical structure (chapter/heading/subheading), details what each parameter returns (code returns hierarchy; section browses), and provides concrete examples of query behavior. This goes well beyond the schema.

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

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

The description clearly states the tool searches 6,940 WCO HS 2022 commodity codes, specifying the resource and action. It also distinguishes itself from siblings by naming uk_duty_calculator and ics2_check as related tools with different purposes.

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

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

Provides explicit usage instructions: 'Provide ONE of: query, code, or section,' and explains when to use each. It also names alternatives and clarifies that ics2_check is a different check entirely.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds substantial behavioral detail: deterministic term matching, flagged terms with notes, the meaning of clean, no binary verdict, rate limits, 429 error handling with retry_after_seconds, and periodic list updates. No contradiction with annotations.

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

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

The description is long but well-structured: purpose, behavior, return format, limitations, and related tools are separated into clear sections. It is front-loaded with the primary function. Though verbose, each sentence earns its place; only minor redundancy exists in describing the return envelope when output schema is present.

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 having an output schema, the description thoroughly explains return fields, limitations, rate limits, legal disclaimers, and the non-exhaustive nature of the list. It provides complete context for an agent to invoke the tool correctly and interpret results.

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

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

Schema coverage is 100% and the schema description already states 'The goods description to check against the EU ICS2 stop-words list.' The description's 'Pass description=<goods description>' is redundant with the schema. No additional parameter semantics are provided beyond what the schema already offers.

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

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

The description opens with a specific verb+resource: 'Check a goods description against the official EU ICS2 stop-words list', clearly scoping the tool to a distinct function. It explicitly differentiates from siblings by naming hs_code_lookup and uk_duty_calculator as covering different fields of ENS screening.

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

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

Explicitly states when to use ('Use BEFORE filing an ENS') and what the tool is not for ('not an ENS filing, not a customs-compliance determination, not legal advice'). It also provides alternatives: 'call get_subscribe_link for higher limits' and names hs_code_lookup/uk_duty_calculator for other purposes.

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 (readOnlyHint, idempotentHint, destructiveHint), the description discloses error behavior (unknown code returns valid code list), rate limits (25 requests/day per IP with 429 retry semantics), and limitations (summarised guidance, binding ICC text). This adds significant context the annotations do not provide.

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

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

Every sentence contributes value. The description is well-structured: purpose, mode classification, usage instructions, behavior, return fields, limitations, and related tools. No redundancy or filler—information is dense but organized.

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

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

Given the tool's moderate complexity (2 optional params, output schema present), the description is fully complete. It covers parameter combinations, error handling, rate limits, response structure, limitations, and related tools. There is nothing left ambiguous for an agent deciding to use and invoke this tool.

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

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

Although the schema covers parameter descriptions (100% coverage), the description adds meaning about how the parameters interact: code for a single rule, category for filtering, or neither for all results. It also clarifies the category enum values (any_mode vs. sea_only) with concrete examples of the rules belonging to each.

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

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

The description uses a specific verb ('Look up') and clearly identifies the resource ('the 11 Incoterms 2020 trade rules'). It defines exactly what information is provided (who pays for transport, insurance, customs, and risk transfer), which distinguishes it from other lookup tools in the sibling list.

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

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

The description explicitly explains when to use each input combination: provide a code for one rule, category for a filtered list, or neither for all 11. It also notes the transport-mode applicability (any mode vs. sea-only) and lists related tools (uk_duty_calculator, shipment_summary), giving clear alternatives and context.

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

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

Annotations already indicate read-only and idempotent behavior. The description adds substantial behavioral context: deterministic calculation, stacking behavior (stackable=true with stack_height 2 or 3 divides floor footprint), fits logic based on vehicle length, rate limiting with 429 retry guidance, and response envelope details. These are not present in annotations and significantly help the agent anticipate side effects and error handling.

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

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

The description is rich but tightly organized: core definition, usage requirements, behavior details, rate limits, return structure, and related tools. Every sentence contributes value, and it front-loads the most critical information. Though longer than typical, it remains efficient and scannable.

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

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

Given the tool's complexity (9 parameters, output schema, rate limits), the description is exceptionally complete. It covers preconditions, error behavior, response fields, and sibling relationships. The existence of an output schema does not weaken the description, which still clarifies the semantics of returned values like utilisation_percent and fits.

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?

Though the schema covers 100% of parameters, the description adds relational and conditional meaning that the schema cannot express: the mutual exclusivity of pallet vs custom dimensions, the effect of stackable/stack_height on results, and the dependency of weight_kg on payload validation. This elevates parameter understanding beyond individual attribute descriptions.

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

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

The description opens with a specific, action-oriented statement: 'Calculate loading metres (LDM) for European road freight — how much trailer length a pallet load occupies.' It defines LDM and clearly distinguishes this tool from sibling calculators by focusing on linear trailer length for pallet loads, with references to related tools that cover different use cases (e.g., pallet_fitting_calculator, consignment_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?

The description explicitly states when to use the tool and provides alternatives via the 'Related' section. It also provides critical usage constraints: 'Provide a pallet preset OR custom length_mm + width_mm — omitting both errors with a usage hint.' This goes beyond vague guidance and gives actionable selection criteria.

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, and non-destructive. The description adds substantial behavioral context: 'Coordinates are INPUT only — nothing is stored or logged,' 'deterministic distance sort,' the confidence scoring rule ('large airport within 25 km scores high; closed/heliport/seaplane results cap lower'), and the 429 retry behavior. These are non-obvious traits not derivable from annotations or 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?

The description is organized into clear, purposeful sections: summary, input instructions, behavior, return envelope, limitations, and related tools. Each sentence contributes unique information (e.g., data source, rate limiting, navigation disclaimer). While longer than average, no redundant or filler content exists, and the most critical info (what it does and how to use) is front-loaded.

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

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

Given the tool's complexity (rate limits, confidence scoring, output envelope) and the presence of an output schema, the description is remarkably complete. It explains the return structure ('count and results[] ... under result, plus confidence, _source and citation'), the confidence semantics, rate-limit handling with retry headers, and the reference-data limitation. This exceeds what schema and annotations alone provide.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds only marginal parameter context beyond the schema: it reiterates latitude/longitude format, lists optional parameters (radius_km, max_results, type), and gives an example value for type ('e.g. large_airport only'). It does not provide new semantics like edge-case warnings or format specifics not already in the schema.

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

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

The description opens with a specific action: 'Find the airports nearest to a caller-provided latitude/longitude, sorted by great-circle (haversine) distance with distance_km on each result.' This clearly identifies the resource (airports) and the unique value (proximity sorted by distance). It also distinguishes itself from sibling tools via the 'Related' section, naming airport_lookup as exact code/name lookup with no distance, and unlocode_lookup as named transport-location search.

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

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

The description explicitly states when to use the tool ('pass coordinates you already hold'), when not to use it ('does NOT geocode place names and does NOT compute routes'), and names alternatives ('Related: airport_lookup... unlocode_lookup...'). It also provides practical guidance on rate limits: 'back off and retry, or call get_subscribe_link for higher limits.' This goes beyond implied usage.

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

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

Beyond the annotations (read-only, idempotent, non-destructive), the description adds substantial context: deterministic geometric packing, default pallet deck height of 15, error behavior on invalid dimensions, rate limiting with retry semantics, and limitations regarding real-world stacking rules. No contradictions with annotations.

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

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

The description is well-structured into Purpose, Behavior, Returns, Limitations, and Related sections. Every sentence contributes unique information—no tautology or filler. Despite its length, it is front-loaded with the core purpose and remains scannable.

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

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

Given the tool's complexity (10 parameters, output schema present), the description is comprehensive: it covers return envelope fields, error handling, rate limiting, weight capping behavior, and limitations. Since an output schema exists, it does not need to explain every return field, but it still gives a high-level overview of the response.

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 value by specifying defaults (pallet_deck_height_cm defaults to 15, allow_rotation defaults to true), explaining the effect of max_payload_kg, and noting that missing/non-positive dimensions error naming the parameter. This goes beyond the schema's basic type descriptions.

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

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

The description opens with a specific verb and resource: 'Calculate how many identical boxes fit on a pallet' and enumerates outputs (boxes per layer, layer count, totals, volume utilisation, weight capping). It also distinguishes itself from sibling tools by naming ldm_calculator, vehicle_lookup, and container_lookup with their distinct scopes.

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

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

The description explicitly states what the tool does not model ('does not model interlocked or mixed-orientation patterns'), when weight capping applies, and how to handle rate limits (back off, retry, or call get_subscribe_link). It also lists related tools, giving clear alternatives.

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

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

Description discloses internal call-outs ('calls the ldm_calculator, adr_lookup and uk_duty_calculator engines directly'), the 2.40 m loading-metre divisor, the non-stackable default, palletSpaces as floor positions vs palletRows, warning instead of failure behavior, and 429 handling with retry_after_seconds. This goes well beyond the annotations and does not contradict them.

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

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

The description is long but appropriately so for a composite tool with seven parameters and mode-specific behavior. It is well-structured with clear sections (Behavior, Returns, Limitations, Related) and each sentence carries a distinct piece of information with no filler.

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

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

Given the tool's complexity—multiple modes, nested items, output schema, and several related siblings—the description is complete. It covers inputs, units, mode-specific outputs, failure behavior, rate limits, limitations, and alternative tools, making it more than sufficient for an agent to decide when and how to invoke it.

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%, but the description still adds value by grouping parameters ('items[] (dims in cm, weight in kg, quantity; optional stackable, pallet_type, hs_code, un_number, customs_value)') and explaining nuanced behavior like 'an item with no stackable flag is NOT stacked'. It also clarifies that origin/destination and incoterm refine the duty leg, which the schema does not convey as explicitly.

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 'Composite shipment analysis in one call' and enumerates specific outputs (volume, gross/chargeable weight, road LDM, vehicle suggestion, volumetric weight, revenue tonnes, container suggestion, ADR presence, UK duty estimates). This clearly distinguishes it from single-purpose siblings like cbm_calculator 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?

The description explicitly frames this as the composite option and names alternatives: consignment_calculator, cbm_calculator, chargeable_weight_calculator, ldm_calculator, adr_lookup, and uk_duty_calculator, noting which are called as engines and which are single-purpose equivalents. It also gives rate-limit retry guidance and references get_subscribe_link for higher limits.

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 readOnlyHint/idempotentHint annotations, the description discloses live fetch behavior, deterministic arithmetic, HMRC error messages, origin-dependent warning surfacing, rate limiting details (429 retry_after_seconds and Retry-After header), and response envelope properties like validity.as_of and _source. No contradiction with annotations.

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

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

The description is densely informative but well-structured: purpose, formula, inputs, behavior, returns, limitations, related tools. Every sentence adds functional value, and key information is front-loaded in the first sentence. No filler or repetition.

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

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

Given the tool's complexity, the description covers all essential aspects: live data source, calculation logic, required and optional inputs, error/rate-limit behaviors, output structure, limitations, and related tools. The output schema and annotations further enrich context, but the description is fully self-sufficient.

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?

While schema coverage is 100%, the description adds critical semantic relationships: it defines CIF as customs_value + freight_cost + insurance_cost and explains how duty and VAT are calculated from these components. This goes beyond the individual parameter descriptions and clarifies how parameters interact.

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: 'Estimate UK import duty and VAT for a commodity code using the LIVE GOV.UK Trade Tariff'. It clearly distinguishes itself from siblings by emphasizing live rates fetched per request and explicitly relating to hs_code_lookup and incoterms_lookup for different steps.

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

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

Provides explicit usage context: required vs optional parameters, formula for CIF, error scenarios, rate limits with actionable retry guidance, and alternatives like get_subscribe_link for higher limits or hs_code_lookup to find the code first. Limitations and when-not-to-use are clearly stated.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description discloses rate limits, 429 retry semantics, provenance status, data quality caveats, and the meaning of PENDING provenance. It also explains the envelope structure and pallet-specific quirks, adding substantial context without contradicting annotations.

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

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

The description is thorough but verbose, running into a long block of text without clear section breaks. While front-loaded with the core purpose, it then spends many sentences on provenance and data quality nuances that, while valuable, could be condensed or structured. It earns a 3 for being overlong, not for lacking substance.

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

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

Given the tool's complexity (16 record types, filters, rate limits, output envelope, provenance), the description covers all critical aspects: return format, error behavior, limitations, and related tools. No significant gap remains; it even explains the envelope's provenance_status and the subtlety of corroboration counting.

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

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

The schema already documents all three parameters, but the description enriches them: explains type accepts IATA codes or slugs, omit to list all, and clarifies that category/deck filter the list. It also warns that pallets lack internal dimensions, directly affecting how parameters map to data.

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

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

The description clearly states the tool's purpose: looking up air-cargo ULD specifications, with specifics on the 16 types and their attributes. It distinguishes itself from siblings by naming related tools (chargeable_weight_calculator, container_lookup, airline_lookup) and clarifying scope (air cargo vs sea freight).

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

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

Provides explicit usage scenarios: omit type to list all, use category/deck filters, and error handling for unknown types. It gives alternatives to related tools and advises confirming critical dimensions with the carrier. This is rich, actionable guidance for when and how to use the tool.

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?

Adds that the conversion is deterministic, names both units and formula in response, errors on cross-dimension conversions with an accepted-unit list, and documents rate limiting (429 with retry_after_seconds/Retry-After header) and the get_subscribe_link fallback. This is substantial context not in annotations, which only declare read-only and idempotent.

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?

Though long, every sentence adds essential info: unit list, special behaviors, error handling, rate limits, return envelope, and sibling guidance. It is organized in paragraphs and front-loaded with the primary purpose.

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

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

For a tool with three params and an output schema, the description covers intended use, edge cases, failure modes, rate limiting, response structure, and related tools. Nothing critical 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% with enums, but the description explains the special meaning of chargeable_kg (IATA 6,000 divisor, 1 CBM=166.67 kg), freight_tonnes (W/M), and the constraint that they are only valid from cbm. It also defines short/long/metric ton conversions, enriching the unit 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?

Description opens with 'Convert freight and logistics units' and enumerates weight/volume/length categories plus the two freight-specific targets. The 'Related' sentence distinguishes it from cbm_calculator and chargeable_weight_calculator, making the tool's unique scope clear.

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

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

Explicitly names alternatives: 'cbm_calculator (dimensions to volume first), chargeable_weight_calculator (proper air billing weight with pieces and a custom divisor)'. The special-target explanation (valid only FROM cbm) clarifies when this converter is the right choice vs the dedicated calculators.

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, and destructiveHint false. Description adds substantial context beyond that: read-only behavior for exact code vs confidence reporting for fuzzy hits, not-found error semantics, 429 rate-limit handling with retry_after_seconds and Retry-After header, and cautions about administrative code list accuracy. No contradictions with annotations.

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

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

Though multi-paragraph, every sentence earns its place: overview, usage modes, behavior/rate limits, return envelope, limitations, related tools. Well-structured and front-loaded with purpose. No redundant filler; the length is appropriate for the tool's complexity.

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

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

Given 5 optional params, an output schema, and annotations, the description still adds essential context: return envelope specifics (confidence, _source, citation), error semantics, rate-limit handling, and realistic use limitations. It is complete enough to safely invoke the tool without prior knowledge.

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. However, description adds valuable semantics not in schema: explains the 5-character code structure (2-letter ISO + 3-letter location code with examples), clarifies query can be name or code, and states limit default/max and min length for query. This enriches parameter understanding beyond schema definitions.

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

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

Description opens with a specific verb ('Search') and a precise resource (116,232 UN/LOCODE transport locations), enumerating port/airport/rail/road/terminal types. It clearly distinguishes from siblings by mentioning related airport_lookup and nearest_airport tools, making its scope unambiguous.

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

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

Provides explicit when-to-use guidance: exact code vs fuzzy name query, optional country/function_type narrowing, and limit behavior. Names alternatives directly: 'Related: airport_lookup ... nearest_airport ...' and even tells users to call get_subscribe_link for higher rate limits. This is exemplary usage guidance.

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

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

Annotations already indicate readOnly/idempotent, so the bar is lower, but the description adds substantial behavioral context: deterministic arithmetic, per-identifier output fields, rate limits (25 req/day) with retry_after_seconds and Retry-After header, empty found[] behavior, and the structural-only limitation. This goes well beyond the annotation safety profile without 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?

Organized into labeled sections (modes, behavior, returns, limitations, related) that move from purpose to operational detail. Every sentence contributes essential content—rate limits, output envelope, structural caveat, alternatives—without redundancy. The length is justified by the tool's complexity.

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

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

Covers all materially relevant aspects: the two input modes, per-type validation details, output structure, error/rate-limit handling, limitations, and related tools. An output schema exists but the description still adds contextual value, making the tool fully understandable without external documentation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful mode-level semantics: text is for parse mode, value+type is for single validation, and the type enum maps to specific standards. This clarifies the mutual relationship between parameters that the schema does not express, justifying a small increment 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?

The description opens with a specific verb+resource: 'Validate and parse freight identifiers by their public check-digit algorithms', naming the three identifier types. It distinguishes itself from siblings in the Related section, explicitly calling out container_lookup and airline_lookup as different in scope.

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

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

It gives explicit when-to-use guidance with two modes (text for scanning arbitrary strings, value+type for single validation). It names alternatives (container_lookup, airline_lookup) and excludes registry/tracking use via 'STRUCTURAL ONLY'. Rate-limit handling instructions (back off/retry or get_subscribe_link) are also actionable.

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 readOnlyHint=true annotation, the description discloses specific error behavior ('an unknown slug errors with the valid list'), rate limiting with 429 handling and retry instructions, the response envelope (result, confidence, _source, citation), and provenance status. This goes well beyond the annotation's simple safety signal and sets expectations accurately.

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

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

The description is structured into clear paragraphs (overview, usage, behavior, returns, limitations, related) with no redundant fluff. Each sentence adds distinct information: scope, fields, filtering, error handling, rate limits, response shape, caveats, and cross-references. It is long but every part earns its place.

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

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

The tool has an output schema, but the description still explains the response envelope and provenance_status, and it notes limitations about typical specs and legal payload. Given the simple 3-optional-param API, the description covers all necessary context: what, how, when, errors, rate limits, and relationships to sibling tools.

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 description adds usage semantics on top: omitting slug lists all records, while category and region filter the list. It gives a concrete slug example and enumerates allowed enum values, making parameter behavior intuitive beyond the schema's short descriptions.

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

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

The description opens with 'Look up road-freight vehicle and trailer specifications' — a specific verb and resource — then enumerates 17 vehicle types and the data fields each record carries. It is clearly differentiated from sibling lookup tools (e.g., container_lookup, uld_lookup) by focusing on road-freight equipment and even names related calculators as alternatives.

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 explains how to call it: 'Provide slug... omit it to list all 17; category... and region... filter the list.' It also provides contextual alternatives under 'Related', such as 'ldm_calculator (whether a pallet load fits)', signaling when to choose another tool. It mentions get_subscribe_link for rate-limit mitigation, giving a clear path for when this tool's limits are insufficient.

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