FreightUtils MCP Server

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

Annotations already indicate read only and idempotent. Description adds deterministic arithmetic, error handling for unresolved UN numbers, rate limit behavior with retry guidance, and limitations (not legal advice, core duties remain). 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 well-structured with front-loaded purpose, logical sections, and no fluff. Slightly verbose but each part adds necessary detail. Could be tightened slightly but overall very good.

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 complexity, the description covers purpose, usage, behavior, parameters, output structure, limitations, and related tools. With output schema present, it sufficiently describes return fields and provides comprehensive context.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by explaining precedence (items over un_number+quantity) and clarifying units (kg or litres per ADR unit). Also describes calculation logic giving context to parameters.

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

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

The description clearly states the tool calculates ADR 1.1.3.6 exemption points for dangerous-goods loads, specifying the verb 'Calculate' and resource. It distinguishes from sibling tools adr_lookup and adr_lq_eq_check by naming them and explaining their 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?

Explicitly provides when to use (calculating exemption points), when not to use (e.g., for LQ/EQ relief routes), and alternative tools. Also mentions rate limits and suggests 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?

Annotations already declare readOnlyHint=true. Description adds crucial behavioral details: rate limits (25/day per IP), error codes (NOT_FOUND, 429) with retry hints, input normalization, and the fact that it's a factual compilation not legal advice.

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: main purpose first, then parameter details, behavior, returns, limitations, and related tools. Each sentence adds value, though could be slightly more concise.

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

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

Given the presence of an output schema (mentioned in context signals) and the detailed description of return fields (count, results[]), the description is complete. It also covers limitations and verification responsibility.

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 3. Description adds normalization details (e.g., 'UN1203' and 'un 1203' equivalent) and examples for each parameter, providing value beyond the schema.

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

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

The description clearly states it looks up European road dangerous-goods (ADR 2025) reference data, listing specific fields. It distinguishes from siblings like adr_lq_eq_check and adr_exemption_calculator by noting related tools at the end.

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 exactly one of un_number, search, or hazard_class. Describes when to use each (exact lookup, partial match, class filter) and limits (up to 50 entries for search, up to 100 for class).

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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds deterministic behavior, rate limiting (25/day per IP, 429 error with retry info), and output structure details. No contradiction, supplements well.

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-structured with clear sections (purpose, usage, behavior, limitations, related). Slightly verbose but each sentence adds value. Front-loaded with key information.

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

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

Comprehensive for a compliance lookup tool with output schema. Covers what it does, how to use, behavioral notes, limitations, and related tools. No gaps given the domain complexity.

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 100% of parameters with descriptions. Description adds context: mode explanation, quantity per inner packaging, units clarification, inner_packaging_qty for EQ mode. Adds value beyond 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 checks ADR LQ/EQ exemption eligibility with specific verb and resource. It distinguishes from sibling tools adr_lookup and adr_exemption_calculator by explaining their 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 clear usage instructions: mode, items format, and quantity interpretation. Mentions rate limits and alternative for higher limits. Implicitly excludes when full compliance check is needed via limitations section, but lacks explicit when-not-to-use statement.

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, etc.), the description expands on behavior: fuzzy match quality (confidence, FUZZY_BEST_MATCH advisory), no-hit behavior (count 0, NO_MATCH advisory), rate limiting details (25 req/day, 429 with retry info), and the return structure. It also notes a limitation about provenance, adding trust 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 detailed but well-structured with clear paragraphs for different aspects (purpose, parameters, behavior, returns, limitations, related). It is front-loaded with the main purpose. Slightly long but every sentence contributes value.

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

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

Given the complexity (multiple search modes, fuzzy matching, rate limits, return format, limitations, sibling tools), the description is comprehensive. It covers all necessary context for an agent to select and invoke the tool 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% and descriptions exist, but the tool description adds meaning: 'query is a ranked fuzzy search across names and codes' vs 'exact filters' for others. It explains the single parameter constraint and what AWB prefix means, enhancing understanding beyond 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,357 airlines by multiple criteria (name, IATA, ICAO, AWB prefix, country). It explicitly distinguishes from siblings like airport_lookup and validate. The verb 'Search' and resource 'airlines' are specific.

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 instructs to provide exactly one parameter and differentiates fuzzy search (query) from exact filters (iata, icao, prefix, country). It also mentions rate limits and suggests get_subscribe_link for higher limits, and points to related tools.

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

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

Beyond annotations (readOnlyHint, idempotentHint), description adds behavioral details: exact code hits return one record, ambiguous searches return ranked candidates with match quality (confidence), unknown code errors with not-found message, and rate-limiting behavior. Also describes return structure.

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 well-structured and informative, but slightly verbose. Each sentence adds value; however, it could be streamlined without losing key information. Overall efficient.

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 (4 parameters, output schema, rate limits, error handling), the description covers all necessary aspects: behavior, return format, limitations, related tools, and error handling. No significant gaps.

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

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

Schema coverage is 100%. Description adds meaning by specifying mutual exclusivity of iata/icao/query, that type is an optional filter, and that query requires at least 2 characters. These details are not in the schema itself.

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 clearly states the tool looks up an airport by IATA code, ICAO code, or free-text search. It differentiates from siblings like nearest_airport, airline_lookup, and unlocode_lookup by explicitly mentioning them in '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?

Explicitly states to provide exactly one of iata, icao, or query, and that type is optional. Gives guidance on rate limiting (429 error handling, retry, and use get_subscribe_link for higher limits) and mentions limitations (reference data only, not for navigation).

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

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

The description adds significant behavioral context beyond annotations: deterministic behavior, error messages for missing/non-positive dimensions, rate limits (25 requests/day per IP), 429 error with retry_after_seconds, and a suggestion to call get_subscribe_link for higher limits. 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 well-structured with sections for purpose, behavior, returns, and related tools. It is front-loaded with main purpose. Some background info (e.g., 1 CBM definition) is slightly verbose but not detrimental. Overall efficient for the information provided.

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 existence of a complete output schema and full parameter coverage, the description covers all necessary aspects: purpose, behavior, error handling, rate limits, return fields, and related alternatives. It provides a comprehensive understanding without gaps.

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

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

Schema has 100% description coverage, so baseline is 3. The description adds value by explaining validation behavior (error naming missing parameter) and default for pieces. While not extensive, it provides practical context 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 'Calculate cubic metres (CBM) for a shipment from per-piece dimensions' and distinguishes the tool from siblings by listing related calculators such as chargeable_weight_calculator, consignment_calculator, etc. It specifies the exact resource and action.

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 guidance on when to use this tool versus alternatives by listing related calculators and their purposes. It also explains rate limits and error handling, giving clear context for usage.

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

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

Annotations indicate read-only, non-destructive, idempotent. The description adds deterministic behavior, rounding of per-piece volumetric weight, error messaging for invalid inputs, and rate-limiting details. 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, front-loading the core purpose, then behavioral details, return structure, and related tools. Each sentence adds value, though slightly verbose; could be tightened while retaining all info.

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 (per context signals), the description sufficiently covers return values, error states, rate limiting, and related tools. It addresses all aspects needed for correct agent invocation.

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

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

Description explains the factor parameter as volumetric divisor with defaults (6000 vs 5000) and pieces as number of identical pieces. It mentions rounding per piece. Schema coverage is 100%, but the description adds valuable context 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 explicitly states the tool calculates air freight chargeable weight as the greater of actual and volumetric weight. It distinguishes from siblings like cbm_calculator, consignment_calculator, and uld_lookup, and clarifies it is air mode only.

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 instructs when to use (air mode only) and when not to (use consignment_calculator for sea). It mentions rate limits and how to handle 429 errors, and suggests get_subscribe_link for higher limits. Alternative tools are explicitly named.

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

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

The description adds substantial behavioral context beyond annotations: deterministic calculation, advisory-only flags (implausible density, mode/option mismatch, dangerous goods, check-digit sanity), error handling (invalid lines error naming offending field), rate limiting with retry guidance, and explicit limitations (not regulatory advice). It does not contradict the annotations (readOnlyHint, idempotentHint, destructiveHint are all consistent).

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 front-loaded core output, followed by input explanation, behavioral details, rate limits, return structure, limitations, and related tools. While comprehensive, it is slightly verbose in listing all flags and limitations. Every sentence earns its place, but could be tightened slightly. A clear example or shorter phrasing would improve conciseness.

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

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

Given the tool's complexity (multiple modes, input formats, flags, rate limits, output schema present), the description is remarkably complete. It covers what, how, behavior, errors, returns, limitations, and related tools. With an output schema, it appropriately omits detailed return field descriptions. No significant gaps remain for an AI agent to safely invoke 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?

With 100% schema description coverage, the baseline is 3. The description adds value by explaining the purpose of parameters (e.g., mode selects chargeable-weight basis, options affect air divisor, lines vs items), defaults (mode default road, air divisor default 6000), and relationships (provide lines OR items). This contextual information goes beyond the schema's individual 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 clearly states that the tool calculates per-line and grand totals for multi-item mixed consignment, including specific metrics (CBM, LDM, volumetric weight, chargeable figure) and advisory flags. It distinguishes from siblings by explicitly naming single-figure calculators (cbm_calculator, chargeable_weight_calculator, ldm_calculator) and shipment_summary, making it easy to differentiate when to use this versus related tools.

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

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

The description provides clear context on when to use the tool (for multi-item mixed consignment) and alternatives (single-figure versions, shipment_summary). It explains the canonical (lines) vs legacy (items) input forms and default mode. Although it doesn't explicitly state when not to use, the mention of related tools for simpler scenarios sufficiently guides usage.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context: rate limits with 429 error handling, geometric fit best-effort, provenance status, and limitations about manufacturer-typical specs. 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?

Description is detailed and well-structured, front-loading purpose immediately. Each section (behavior, returns, limitations, related tools) earns its place. A minor reduction in length could be possible, but overall it is efficient for the complexity.

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

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

Given the complexity (optional fit calculations, rate limits, error handling, multiple use cases) and the presence of an output schema, the description covers all necessary aspects: returns, error behavior, limitations, and related tools. It provides sufficient context for the agent to use the tool 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% with a description for the only parameter 'type'. The description adds value beyond schema by explaining slug format, examples, omitting to list all, and how to add item dimensions for fit calculations. It provides practical usage guidance.

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

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

The description clearly states it retrieves ISO shipping-container specifications with optional load-fit calculations. It distinguishes from sibling tools like uld_lookup (air-freight equivalent) and validate (check digit), and uses a specific verb-resource combination ('Get ISO shipping-container specifications').

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 (get specs, compute fit) and when not (not for load distribution, mixed cargo). Provides alternatives like get_subscribe_link for higher rate limits and lists related tools (validate, cbm_calculator, etc.).

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, idempotent, non-destructive. The description adds substantial behavioral details: deterministic, fleet-average factors with empty running included, low representativeness for sea/air, rate limiting with 429 handling, return format including confidence and citation. 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?

Well-structured with clear sections (purpose, important notes, behavior, returns, limitations) and front-loaded core formula. Every sentence adds value without redundancy. Efficient yet comprehensive.

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 tool complexity (7 params, 3 required, 4 enums, output schema exists), the description is fully complete: explains formula, parameter roles, edge cases (unknown sub_mode), rate limits, return fields, and limitations. No gaps remain for an agent to infer.

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 parameters (100% coverage). The description adds critical semantic value beyond schema: explains mass must be actual gross (not volumetric), distance must be provided, sub_mode unknown returns available:false, and region defaults to per-mode. Provides important usage context for each parameter group.

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 estimates freight transport greenhouse-gas emissions per ISO/GLEC standards, specifies the formula, and distinguishes it from sibling tools like cbm_calculator, ldm_calculator, and chargeable_weight_calculator by explicitly stating those handle sizing/billing while this one estimates CO2e.

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 on when to use (when emissions estimate needed) and when not (does not route or compute distances). Highlights common mistake (avoid volumetric weight for air freight) and points to get_subscribe_link for rate limits. Offers clear differentiation from related tools.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. Description adds key behavioral details: static local response, no API call, never rate-limited, and that the URL must be handed to the user.

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 clear sentences: purpose/usage, behavior, return value and agent instruction. No wasted words.

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

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

Given the tool's simplicity (one optional param, annotations present, output schema exists), the description covers all necessary context: when to use, what it does, behavioral traits, and explicit agent constraint.

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 a single parameter 'tier' having explicit enum and description. Description adds no additional parameter semantics beyond what's in schema, so baseline 3 is appropriate.

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

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

Clearly states the verb (Get), resource (URL), and purpose (subscribe to FreightUtils Pro for higher API limits). Distinct from sibling tools which are all calculators or lookups.

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 specifies when to use: when user asks about upgrade/pricing or after 429 errors. Also provides a negative guideline: agents must not complete subscription.

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 and idempotentHint. Description adds: keyword-based description search, rate limits with 429 handling, return envelope details, and limitations (indicative, not binding). No contradictions.

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-structured: purpose, parameters, behavior, limitations, related tools. Front-loaded with main action. Slightly long but every sentence serves a purpose; could be more compact but effective.

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?

Complete coverage: parameter choices, search behavior, return fields (query/code echo, count, results with hscode/description/hierarchy), error handling (429), limitations, and references to sibling tools. Output schema exists, but description still enriches understanding.

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 three parameters with patterns and descriptions. Description adds context: for 'code' it returns hierarchy, for 'query' it explains word matching, and for 'section' it specifies Roman numeral range. Adds value beyond 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 HS 2022 commodity codes. It specifies the 6-digit international layer and distinguishes from siblings like uk_duty_calculator and ics2_check, making the purpose 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?

Explicitly instructs to provide ONE of query, code, or section, and explains when each is appropriate. Gives examples of search behavior (e.g., 'laptop' returns zero rows, prefer formal wording). Mentions rate limiting and related tools for further steps.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=false. The description adds deterministic term matching, notes on standalone vs embedded stop-words, rate limit behavior (429 with retry info), and explicitly states it does not give a binary pass/fail verdict. No contradictions.

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 comprehensive but slightly verbose. However, it is well-structured with a clear order: purpose, behavior, returns, limitations, and related tools. Each sentence adds value, so it earns a high conciseness score.

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

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

Given the tool's complexity (rate limiting, deterministic matching, legal basis), the description covers all necessary aspects: input, behavior, return fields, limitations, and sibling differentiation. An output schema exists, so return values are explained.

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 parameter 'description' described in the schema. The description adds context like 'deterministic term matching' and clarifies the input is a goods description, providing meaningful nuance 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 explicitly states the tool checks a goods description against the official EU ICS2 stop-words list, using specific verbs ('check', 'pass description'). It distinguishes the tool from siblings by naming hs_code_lookup and uk_duty_calculator as related but different tools.

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

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

Provides clear guidance: 'Pass description=<goods description>', explains when to use ('Use BEFORE filing an ENS'), and gives alternatives for rate limits ('call get_subscribe_link for higher limits'). Also clarifies what the result does and does not mean ('clean=true does NOT guarantee acceptance').

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 provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds: read-only reference behavior, error specifics for unknown code, rate limit details (25 requests/day/IP), retry guidance, and return envelope structure (result, confidence, _source, citation). No contradiction.

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

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

Well-structured with front-loaded purpose, then mode details, usage, behavior, return, limitations, related tools. Every sentence adds value; slightly long but warranted due to detail. Could be slightly tighter but not wasteful.

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 2 parameters, 100% schema coverage, no required params, presence of output schema, and tool complexity, description covers all: input options, behavioral details (error, rate limits), output structure, limitations, and related tools. No gaps.

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

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

Schema coverage is 100% with both parameters described. Description adds meaning: code pattern (3 letters) and category enum values are already in schema, but it explains the combined behavior (code for one rule, category for filtered list, neither for all) and the result of unknown code. Goes beyond baseline 3.

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

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

Description clearly states it looks up the 11 Incoterms 2020 trade rules, specifying who pays, insurance, customs clearance, and risk transfer. It distinguishes from siblings by noting related tools (uk_duty_calculator, shipment_summary) and scope as a reference 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?

Explicitly says when to provide code, category, or neither; describes error handling for unknown codes (returns valid code list) and rate limiting (429 with retry_after_seconds and retry strategy). Names alternatives (uk_duty_calculator, shipment_summary) for related 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?

Annotations show read-only and idempotent. Description adds deterministic behavior, stackable logic, fits reporting, and rate limit details (429 retry). No contradiction.

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

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

Well-structured and front-loaded with purpose. Some redundancy (e.g., rate limit explanation could be shorter), but overall efficient.

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 input requirements, behavior, rate limits, related tools, and output fields. Output schema exists, so return values are adequately explained.

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 100%. Description adds context: parameter combinations (preset vs custom), stackable/stack_height interaction, weight_kg with vehicle. Enhances 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 calculates LDM for European road freight, defines the unit, and distinguishes from siblings like vehicle_lookup and pallet_fitting_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 when to use: provide pallet preset or custom dimensions, omitting both errors; lists related tools for 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?

Beyond annotations (readOnly, idempotent), description adds that coordinates are not stored/logged, explains confidence calculation, and details error behavior for rate limits. 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?

Well-structured: main purpose first, then parameters, behavior, error handling, and related tools. Slightly long but every sentence adds value; no waste.

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 aspects: input parameters, output structure (count, results, distance_km, confidence, source, citation), limitations (reference data, not for navigation), rate limits, error handling, and related tools. Output schema exists but description still explains return envelope.

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. Description adds practical context like defaults (max_results default 10), ranges (1-50), and clarifies that coordinates are input-only. Enhances understanding without redundancy.

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 finds airports nearest to given coordinates, sorted by great-circle distance. It distinguishes from siblings like airport_lookup (exact lookup) and unlocode_lookup (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?

Explicitly says it does NOT geocode place names or compute routes, and instructs to pass coordinates directly. Provides alternatives and explains rate limit handling with 429 errors and retry instructions.

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

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

Annotations indicate readOnlyHint=true and idempotentHint=true, and the description adds significant behavioral context: deterministic geometric packing, no interlocked or mixed-orientation patterns, weight capping, default pallet deck height, error naming for non-positive dimensions, rate limiting with retry details, and response envelope fields like confidence, _source, citation.

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

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

The description is a single paragraph covering main purpose, behavior, return fields, limitations, and related tools. While it could be more structured (e.g., bullet points), it is appropriately sized and front-loaded with the core function. Every sentence adds value.

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, high schema coverage, output schema exists), the description is complete. It covers error handling, rate limits, limitations, relation to other tools, and key behavioral details. No gaps are apparent.

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 meaning beyond schema: explains allow_rotation (trying 90-degree rotation), pallet_deck_height_cm default of 15, max_payload_kg caps count, and that missing or non-positive dimensions cause parameter-naming errors. This enriches the 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?

The description clearly states the tool calculates how many identical boxes fit on a pallet, detailing boxes per layer, layer count, totals, volume utilisation, and weight capping. It differentiates from sibling tools like ldm_calculator, vehicle_lookup, and container_lookup by mentioning them as related tools.

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

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

The description provides explicit guidance on when to use the tool, including rate limits (25 requests/day per IP) and how to handle 429 errors with retry and alternative (get_subscribe_link). It also explains limitations, such as not modeling interlocked patterns or real-world stacking rules, guiding agents to use alternative tools when needed.

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 and idempotentHint; the description adds substantial behavioral details: it chains deterministic engines, returns partial results via warnings, describes rate-limit handling (429 with retry_after_seconds), and specifies the output envelope format (camelCase field names, confidence, _source, citation). 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 well-structured with clear sections: purpose, inputs, behavior, output, limitations, and related tools. It is front-loaded with the most important information. However, it is somewhat verbose; a few sentences could be trimmed without losing value, but overall it is efficient.

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 (7 parameters, composite calculations, rate limits, multiple output fields), the description covers all necessary aspects: input requirements, behavioral guarantees, error handling, output structure caveats, limitations, and sibling relationships. The existence of an output schema reduces the need to detail return values, and the description still adds important notes on field naming and envelope format.

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 adds critical context: it explains the unit conventions (cm, kg), optional parameters triggering specific calculations (customs_value for duty, un_number for dangerous goods), and parameter relationships (origin/destination/incoterm refine duty). This goes beyond the schema's individual 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?

Description states a specific, composite purpose ('Composite shipment analysis in one call') and enumerates exactly which calculations it performs (CBM, weights, LDM, duty, etc.). It distinguishes from sibling tools like consignment_calculator by noting the composite nature and the camelCase output shape.

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 lists required and optional inputs ('Provide mode and items[]; origin/destination and incoterm refine the duty leg'), explains behavior (warnings for non-runnable sections), and sets expectations for rate limits and error handling. It also clarifies the tool's limitations ('planning summary, not a quotation') and references alternative tools.

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

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

The description adds rich behavioral context beyond annotations: live lookup, deterministic arithmetic, error messages for unknown codes, rate limit handling with retry_after_seconds, and warnings for origin-dependent measures. Annotations already indicate readOnlyHint=true and idempotentHint=true, which are consistent.

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 fairly long but well-structured with clear sections: purpose and calculation, required inputs, behavior and errors, returns, limitations, and related tools. It is front-loaded with the core purpose. Slightly verbose but every sentence adds value.

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

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

Given the tool's complexity (6 parameters, output schema, live data source), the description covers all necessary context: input definitions, calculation logic, error handling, rate limits, output fields, limitations, and related tools. It is comprehensive enough for an agent to use 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?

Parameter semantics are enhanced beyond the input schema. The description explains that CIF value is composed from customs_value + freight_cost + insurance_cost, and provides guidance on formats and optionality. Schema coverage is 100%, but the description adds meaningful context.

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: 'Estimate UK import duty and VAT for a commodity code using the LIVE GOV.UK Trade Tariff'. It specifies the verb (estimate), the resource (UK import duty and VAT), and the data source. It also distinguishes from siblings by naming related tools like hs_code_lookup and incoterms_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?

The description provides explicit when-to-use context: when you need to estimate UK import duty and VAT. It also states when not to rely on it (not a customs ruling) and suggests alternatives (confirm with customs broker or HMRC). It includes error handling for unknown codes and rate limits with retry 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 provides extensive behavioral information beyond annotations: rate limiting (25 requests/day per IP, 429 error handling), error behavior (unknown type returns valid list), provenance and citation included, and limitations (manufacturer-typical specs). 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 comprehensive and well-structured, but slightly verbose. Each sentence adds value, but could be more concise. However, it remains clear and 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?

The description covers all aspects: what the tool does, parameters, return structure, error handling, rate limits, limitations, and related tools. It is complete given the presence of an output schema and annotations.

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% and baseline is 3, the description adds meaning by explaining that 'type' can be an IATA code or slug, and that omitting it lists all ULDs. It also clarifies the category and deck parameters. This adds value beyond the schema.

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

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

The description starts with 'Look up air-cargo ULD specifications' and clearly states the resource and action. It distinguishes from sibling tools by mentioning related tools (chargeable_weight_calculator, container_lookup, airline_lookup) that serve 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?

The description explicitly explains when to use each parameter (e.g., omit type to list all, filter by category or deck). It provides context on related tools for different use cases, guiding when to use this tool versus alternatives.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description adds crucial behavior details: deterministic output, formula disclosure, rate limiting (25 req/day with 429 handling), and specific conversion constraints. 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 with clear paragraphs for units, behavior/errors, and related tools. It is front-loaded with purpose. While comprehensive, it is slightly lengthy; however, every sentence adds value, so it earns a high score.

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

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

Given the tool's complexity (multiple unit categories, freight-specific conversions, error conditions, rate limits, output schema), the description is complete. It covers all necessary aspects, including return structure and related tools, with no gaps.

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

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

The description adds significant meaning beyond the input schema: it explains which units are valid for source/target, notes freight targets are only valid from cbm, and provides conversion formulas (e.g., IATA divisor for chargeable_kg). The schema coverage is 100%, but the description enriches understanding.

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

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

The description clearly states the tool converts freight and logistics units, listing specific weight, volume, length categories, and two freight-specific targets. It distinguishes from siblings by mentioning related tools like cbm_calculator and chargeable_weight_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 provides explicit when-to-use guidance: it notes that cross-dimension conversions and freight targets from non-cbm source error, and references sibling tools for related conversions. It also details rate-limiting and error handling, helping the agent decide when to use this tool or 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?

Discloses read-only behavior, error handling (unknown code returns not-found), match quality reporting via confidence, and detailed rate limit info. Adds context beyond readOnlyHint annotation. No contradiction.

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

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

Well-structured with introductory purpose, usage, behavior/rate limits, return format, limitations, and related tools. Each section serves a clear purpose without redundancy.

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

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

Covers all aspects: input parameters, output format, error behavior, rate limits, limitations, and related tools. Output schema exists, so return values are documented; description complements 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 coverage is 100%, baseline 3. Description adds value with code format explanation and examples, but does not further detail enums beyond 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?

Clearly states verb 'Search' and resource 'UN/LOCODE transport locations' with specific examples. Distinguishes from siblings like airport_lookup and nearest_airport.

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: exact code vs query, optional filters, limit defaults, rate limiting, and what to do on 429. Mentions limitations and related tools, indicating when to use 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?

Beyond annotations (readOnlyHint, idempotent), the description details deterministic check-digit arithmetic, output fields, rate limits (25 req/day per IP, 429 handling), and that validation is structural only. 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 well-structured with clear paragraphs for purpose, modes, behavior, output, and limitations. It is front-loaded with core purpose. However, it is slightly verbose (e.g., repeating output format details that are in the output schema). Still, it's efficient overall.

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, rate limits, output schema, limitations), the description covers all necessary information. It explains how to use, error handling, related tools, and boundaries, making it complete for an agent.

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 descriptions cover all 3 parameters (100% coverage). The description adds value by explaining the interplay between parameters, mode selection, and providing examples. It enhances understanding beyond schema basics.

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 validates and parses three specific freight identifier types (container, AWB, IMO) using check-digit algorithms. It distinguishes from siblings like container_lookup (container TYPE specs) and airline_lookup (AWB-prefix dataset).

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 two modes (text scanning vs single value+type validation), explains when to use each, mentions related tools, and outlines limitations (structural only, not a registry). This provides clear context for when to use this tool versus alternatives.

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

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

The description goes beyond annotations by detailing read-only behavior, rate limits (25 requests/day per IP), error responses (429 with retry_after), and data provenance (typical specs, pending verification). There is 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 well-structured with multiple paragraphs, each serving a purpose. While slightly lengthy, every sentence adds value and there is no redundancy. It effectively uses bullet points in the listing of vehicle types.

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

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

The description is comprehensive, covering return structure (result, confidence, _source, citation), provenance_status, and limitations. Given the tool's complexity and the presence of an output schema, the description fully explains what the tool returns and its constraints.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by providing an example slug, explaining filter usage, and describing error behavior for unknown slugs, which enhances parameter understanding beyond the schema.

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

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

The description clearly states the tool's purpose: looking up road-freight vehicle and trailer specifications. It lists 17 specific vehicle types, explains how to use slug and filters, and distinguishes itself from sibling tools like ldm_calculator and pallet_fitting_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 provides clear guidance: provide a slug for one record, omit to list all, and use category/region filters. It also covers error handling for unknown slugs and rate limits. While it does not explicitly state when not to use the tool, the context is sufficient.

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