ShippingRates MCP Server

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

Annotations already indicate read-only and idempotent behavior. The description adds critical behavioral context: it is a paid API ($0.05 via x402) and returns a 402 with payment instructions if unpaid. It also discloses the exact return shape (array of objects with field names), which goes beyond 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 and concise: purpose first, usage second, payment details third, return format last. Every sentence contributes meaningful information without 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?

For a read-only, idempotent tool with no output schema, the description is remarkably complete. It covers purpose, usage scope, exclusions, payment requirements, error condition, and return structure. Nothing critical is left unexplained.

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 4 parameters with descriptions, so baseline is 3. The description adds context for the payment parameter ('PAID: $0.05/call via x402') but does not elaborate on service, cargo_type, or port beyond the schema. This is consistent with the benchmark's baseline for high schema coverage.

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 fetches Container Freight Station (CFS) handling tariffs, specifically for LCL cargo consolidation/deconsolidation at port warehouses. It distinguishes from siblings by scoping to CFS tariffs and explicitly excluding FCL shipments.

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 usage context: 'Use this for LCL shipments to estimate warehouse handling costs' and excludes FCL shipments. It does not name a specific alternative tool, but the when/when-not guidance is explicit and sufficient.

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

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

Annotations declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds meaningful behavioral context beyond annotations: null fields for unpublished data, 'unknown' severity, the exact source denominator, payment failure returns 402, and the unchanged API envelope. This is rich, non-contradictory disclosure.

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

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

The description is moderately dense but every sentence earns its place: purpose, data behavior, denominator detail, payment, and return envelope. Slightly longer than minimal but front-loaded and well-organized, with no fluff.

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 no output schema, the description compensates by specifying the return envelope shape, null/unknown behavior, payment conditions, and a distinct alternative for advisories. It fully equips an agent to understand tool behavior and select 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 description coverage is 100%, so the baseline is 3. The description repeats the USLAX denominator already present in the port parameter schema but adds no new parameter-specific guidance. It does not compensate beyond the schema's existing detail.

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: 'Get certified port-authority congestion measurements for a specific port.' It clearly distinguishes from sibling tools by naming shippingrates_congestion_news for disruption advisories, which resolves any ambiguity about 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?

Explicitly states when not to use this tool ('For disruption advisories, use shippingrates_congestion_news instead') and provides usage context such as the current certified denominator (USLAX) and the payment requirement. This gives the agent clear decision 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?

The description discloses several behavioral traits not covered by annotations: it is a paid tool ($0.02/call via x402), returns 402 without payment, passes through the API array unchanged, retains all articles in a finite collection window, filters by explicit operational-disruption terms, and never invents alerts. This adds significant context beyond the readOnly, idempotent, non-destructive hints.

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 efficiently structured: a one-sentence purpose statement, a paragraph of behavioral details, sibling differentiation, payment info, and return format. Every sentence carries value and is front-loaded with the most important 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?

Despite having no output schema, the description specifies the return array fields. It covers payment requirements, fallback behavior (402), source limitations, filtering logic, and sibling alternatives. For a read-only news retrieval tool with well-documented parameters, this is a thoroughly complete description.

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% description coverage, so the schema already documents all parameters (port, limit, severity, days_back, x_payment). The description does not add significant parameter-level meaning beyond mentioning the return array fields and the concept of a finite collection window. 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?

The description opens with a specific verb and resource: 'Get certified shipping-disruption publications from reviewed official port-authority sources.' It further clarifies the exact publisher sources (Port of Rotterdam and Port of Los Angeles) and distinguishes itself from sibling tools by naming shippingrates_congestion and shippingrates_risk_score as alternatives for different needs.

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

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

Explicit when-to-use guidance is provided: 'For quantitative measurements, use shippingrates_congestion. For route-level risk scoring, use shippingrates_risk_score.' It also explains behavioral nuances, such as returning empty results rather than fabricating alerts, which informs appropriate use.

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

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

Annotations already declare readOnly, idempotent, non-destructive; the description adds meaningful behavior: storage is never mixed into default D&D, thin coverage yields an explicit 'no data' error (never false $0), and without payment returns 402. It also explains default charge type priority and payment mechanism, all beyond the annotation 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?

Description is organized into clear paragraphs: purpose, usage context, storage caveat, payment, and return summary. While longer than average, each section adds essential guidance, and there is 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?

The description covers return fields (free_days, breakdown, total_cost, etc.), payment requirement, error handling, storage coverage, and the alternative comparison tool. With this level of detail and no output schema, the description fully equips 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 covers 100% of parameters with descriptions, so baseline is 3. The description adds value by explaining charge_type='storage' as a terminal charge distinct from carrier D&D and the default priority order (detention→demurrage→combined). It also clarifies x_payment as a payment header, but the schema already lists this; the added context on storage semantics justifies a 4.

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

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

The opening sentence clearly states 'Calculate demurrage and detention (D&D) costs for one carrier in one country' — a specific verb, resource, and scope. It explicitly contrasts with shippingrates_dd_compare for cross-carrier comparison, distinguishing it from a sibling 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?

Provides explicit when-to-use guidance: 'Use this when the user needs a detailed cost breakdown for a specific carrier.' Names the alternative: 'To compare D&D costs across all carriers at once, use shippingrates_dd_compare instead.' Also clarifies storage as a special case.

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 read-only and idempotent annotations, the description discloses the paid x402 requirement ($0.25/call), the 402 response without payment, and the sorted ascending return format. This adds critical operational behavior not visible from structured data alone.

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 front-loaded with the primary purpose, then provides usage guidance, alternative tool, payment policy, and return format in four efficient sentences. Every sentence adds value 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?

Given the moderate complexity and lack of an output schema, the description sufficiently explains the return structure (array of line, free_days, total_cost, currency, slabs) and sorting order. It also covers payment failure behavior, making the tool fully actionable 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?

Parameter descriptions in the schema already cover country, days, container_type, and x_payment. The description reinforces the three core comparison dimensions (country, container type, detention days) but adds no new parameter-specific meaning 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 compares demurrage and detention costs across all available carriers for a given country, container type, and detention days. It distinguishes itself from the sibling shippingrates_dd_calculate by noting it is for multi-carrier comparison, not single-carrier breakdowns.

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 recommends use for freight procurement and carrier selection, and instructs to use shippingrates_dd_calculate for single-carrier details. This gives clear when-to-use and when-not-to-use guidance with a named alternative.

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?

Despite annotations already declaring readOnly and idempotent, the description adds meaningful behavioral context: the free-time clock starts at a carrier-defined event, arrival_date is taken as user-supplied (data_basis), and non-payment returns 402. It also discloses the charge_family field that distinguishes carrier_dd from terminal_storage.

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 average but every sentence serves a purpose: purpose, usage, data caveat, storage override behavior, payment, and return shape. It is front-loaded with the main query and structured with clear paragraphs, making it easy to skim.

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 no output schema, the description lists all key return fields (free_days_total, days_elapsed, free_days_remaining, etc.), explains failure modes (402 without payment, 'no data' error for uncovered storage lanes), and covers edge cases (charge_family disclosure). It gives an agent everything needed to call 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%, so the baseline is 3. The description adds real value by explaining that arrival_date starts the free-time clock, charge_type overrides the engine priority and 'storage' is a separate terminal charge with thin coverage, and x_payment is required for paid access. These go beyond the schema's 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 a precise statement of what the tool does: 'report how many free days remain, the first chargeable day, the per-diem once charging starts, cost accrued so far, and a forward cost projection.' It also names the sibling tool dd_calculate as the companion for fixed-day questions, clearly distinguishing the countdown use case.

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

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

It explicitly says 'Use this to answer "how long until this container starts costing demurrage, and how much per day?"' and contrasts with dd_calculate. It also provides conditional guidance for charge_type='storage' (terminal storage) and notes thin coverage, plus the payment requirement (x402).

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 context beyond the annotations: payment requirement with 402 behavior, that optional attributes remain null unless certified, and the output shape. It confirms read-only/idempotent nature without contradicting the annotations, and enriches them with operational details.

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 tightly organized: what it does, how to use it, payment, and limitations. Each sentence earns its place with no filler. Front-loaded purpose; payment and behavioral disclaimers are kept separate and 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?

For a lookup tool with 5 optional parameters and no output schema, the description covers the essential context: search criteria, payment, return shape, and unsupported attributes. It gives enough for an agent to decide when to call and what to expect without needing explicit output schema.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining that filters like 'rail_connected' are not asserted unless separately published, which clarifies the actual effect of the parameter. This is beyond the bare 'Rail connectivity filter' schema description, justifying a 4.

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 India's current official ICEGATE ICD/CFS directory' and clarifies the search dimensions (code, name, type). This clearly distinguishes it from the sibling tools like shippingrates_inland_search or shippingrates_cfs_tariffs.

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

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

It explicitly states 'Use this to resolve an official ICEGATE ICD/CFS code or facility name,' giving a clear when-to-use. It also warns about unsupported attributes (GPS, rail, operator, capacity), implying when not to use this tool for such data. However, it does not name specific alternatives, so it stops short of a 5.

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

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

Beyond the readOnly/idempotent annotations, the description adds valuable behavioral details: the rate is 'official ECB daily series', 'updated on ECB working days', 'unsupported currencies fail closed', and it returns cache_age_minutes. This gives the agent a solid model of how the tool behaves.

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 a clear opening sentence, a usage sentence, and a short returns list. The 'FREE' note is extra but relevant for cost-sensitive contexts. It earns its length by including practical details without being verbose.

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 two-parameter read-only tool, the description is complete: it covers what the rate is, how to use it, update frequency, failure behavior, and the exact return shape. No output schema exists, so the explicit returns line fills that gap.

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

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

Schema coverage is 100% with clear examples for both 'from' and 'to'. The description adds a supported currency list and mentions the full ECB daily series, but this is more supplementary than essential semantic enrichment 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 states a specific verb+resource: 'Get the current certified ECB reference rate between two supported currencies.' It clearly differentiates this FX tool from the shipping-focused sibling tools by tying it to currency conversion for shipping cost normalization.

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 provides explicit usage context: 'Use this to normalize costs from different carriers/countries to a common currency for comparison.' It doesn't name alternatives or state when not to use it, but the use case is clear enough among a suite of shipping rates 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 declare readOnlyHint and idempotentHint, but the description adds critical context: ramp and door rates are never mixed in one comparison, payment is required ($0.08/call via x402) with a 402 on failure, and the exact return array structure sorted by rate ascending. This goes well beyond the annotations.

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

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

The description is front-loaded with the core purpose, then flows logically through usage guidance, alternatives, key behavioral constraint, payment info, and return format. Every sentence earns its place; there is no filler or 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?

Given no output schema, the description fully explains the return format (array of specific fields sorted ascending). It also covers payment, delivery_mode behavior, and when to use, making it complete for a tool with 8 parameters and complex sibling relationships.

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 baseline is 3. The description adds no new parameter semantics beyond the schema; it repeats the delivery_mode default and provides an example origin value, but these are already in the schema. No additional meaning is provided.

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 explicitly states it compares inland haulage rates across ALL carriers for a port-to-ICD/city pair, sorted cheapest first. It distinguishes from siblings by naming shippingrates_inland_haulage for single-carrier rates and shippingrates_inland_search for route discovery.

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 guidance: use for carrier selection on inland legs, with clear when-not instructions and named alternatives (single carrier → inland_haulage, route discovery → inland_search). Also explains the delivery_mode default and payment requirement.

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, and destructiveHint=false, so the agent knows this is a safe read. The description adds valuable behavioral context beyond annotations: the payment requirement ($0.05/call via x402) and the 402 error response without payment. It also discloses the return fields, making the tool's behavior more predictable. Missing only minor details like pagination or rate limits, but it's well-covered.

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 compact and front-loaded: purpose first, then use case, then alternatives, then payment, and finally return format. Every sentence earns its place, with no redundant filler. It's long enough to be useful without being verbose.

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 rate-lookup tool with 8 parameters (2 required) and no output schema, the description delivers a complete picture: it explains when to use, what it returns (including the full array structure), payment requirements, and alternatives. Combined with the rich schema annotations, the agent has everything needed to select and invoke this 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 description coverage is 100%, so each parameter has a description with examples and enums. The tool description doesn't add much parameter-level meaning beyond what the schema provides, but it does contextualize x_payment by explaining the payment mechanism and failure mode. That's marginal added value, 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?

The description opens with a specific verb+resource: 'Get inland haulage (trucking/rail) rates for moving containers between a port and an inland location.' It clearly distinguishes itself from siblings by explicitly pointing to shippingrates_inland_search for exploring routes and shippingrates_inland_compare for carrier comparison, making the tool's unique purpose obvious.

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 guidance: 'Use this when you know the specific origin port and destination and need rate quotes.' It also tells the agent what to use instead for route discovery and rate comparison, effectively stating when not to use this tool. This is exactly the kind of decision support 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?

While annotations already indicate read-only and idempotent behavior, the description adds meaningful context: the payment requirement (PAID: $0.03/call, 402 without payment), the return format (array of objects with specific fields), and the search behavior. This goes beyond what annotations offer and no contradiction exists.

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 and well-structured: opening with the main purpose, then usage example, alternatives, payment info, and return format. Every sentence adds value and is front-loaded with the key action.

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 search tool with no output schema, the description is complete: it covers purpose, usage, alternatives, payment behavior, and return structure. Annotations and schema cover the safety profile and parameter details, leaving 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 description coverage is 100% (all parameters have descriptions), so the baseline is 3. The description adds an example keyword search ('ahmedabad') and mentions ICD/CFS in the context of return values, but does not significantly enhance 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 function with a specific verb ('Search') and resource ('inland transport routes'), and differentiates it from sibling tools by naming alternatives for haulage rates and cross-carrier comparison. The example search reinforces the 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?

Explicitly states when to use the tool ('Use this to discover what haulage routes a carrier offers in a country') and gives concrete alternatives ('For actual haulage rate quotes, use shippingrates_inland_haulage. For cross-carrier rate comparison, use shippingrates_inland_compare'). This provides clear guidance on 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?

Annotations already declare readOnlyHint, openWorldHint=false, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context beyond this: it's FREE, returns only reviewed lines with live D&D coverage, and specifies the exact return array shape, which the annotations do not convey.

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

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

The description is compact and well-structured: purpose in the first sentence, usage guidance in the second, cost note, return format, and related tools. Every sentence adds value and 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 zero-parameter read-only list tool, the description is complete: it states what is returned, the intended use case, cost implications, and how it relates to sibling tools. No output schema is needed because the return shape is explicitly described.

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 tool has zero parameters, so the baseline is 4. The description explains the output structure instead, which is helpful since there is no output schema, but no parameter semantics are needed.

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 a specific verb and resource: 'List reviewed shipping-line identities that currently have live D&D coverage, with per-country record counts.' It clearly differentiates from sibling tools by explicitly mentioning related tools and the specific scope of the data returned.

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 an explicit use case: 'Use this to discover which carrier-country D&D combinations are currently available before querying a tariff tool.' It also names alternatives: shippingrates_stats for aggregate totals and shippingrates_search for keyword-based discovery, giving clear when-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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses the payment requirement ($0.05/call via x402) and the 402 error behavior when unpaid. It also describes the return format. These are meaningful behavioral traits not covered by 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 compact and front-loaded: a purpose statement, usage guidance with alternatives, payment note, and return format. Every sentence adds necessary information without redundancy, making it easy for an agent to parse quickly.

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 there is no output schema, the description fully compensates by specifying the exact array structure and fields. It also covers payment behavior, usage context, and related tools. For a read-only tool with this parameter set, nothing essential is missing.

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

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

Schema coverage is 100% (all four parameters described), providing a solid baseline. The description adds value by explaining the x_payment parameter's role in the payment flow and noting that port_code is an optional filter, though it does not deepen the meaning of line or country beyond what the schema already conveys.

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 ('Get') and identifies a clear resource ('local charges at a port for a specific carrier') while enumerating charge types (THC, documentation fees, seal fees). It is easily distinguished from sibling tools like shippingrates_surcharges by focusing on port-specific charges for a named carrier.

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 this tool ('when calculating total shipping costs at origin or destination') and provides named alternatives: combine with shippingrates_dd_calculate or use shippingrates_total_cost for an all-in-one estimate. This gives the agent clear decision 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?

Beyond the readOnly/idempotent annotations, the description discloses payment requirements, the exact fee ($0.01 via x402), and the 402 error behavior without payment. It also specifies the return object shape, going well beyond annotation-provided safety hints.

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 and well-structured, with separate sections for purpose/usage, payment, and return value. Every sentence provides useful information without redundancy, and key details are 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 tool is simple, but the description covers all essential aspects: what it does, when to use it, payment requirements, and exact return fields. Since there is no output schema, the explicit return structure in the description fills that gap completely.

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 does not add significant parameter semantics beyond the schema; the schema already documents the 'code' format and 'x_payment' purpose. The description's reference to search helps usage but not parameter details.

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 function with a specific verb and resource: 'Look up port details by UN/LOCODE' and enumerates the returned fields. It also distinguishes itself from shippingrates_search by explaining that search is for finding codes when unknown.

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

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

Explicit guidance is provided: use this tool to validate port codes or get metadata, and if the UN/LOCODE is unknown, use shippingrates_search first. This directly states when to use the tool and when to use an alternative.

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 important behavioral traits beyond the annotations: unsupported lanes return an empty array, payment is required via x402, and failure without payment yields a 402 with instructions. It also clarifies what the tool does not return (spot quotes). This adds value over the readOnly/idempotent hints.

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 logical blocks: purpose, differentiation, payment, and return format. Each sentence adds essential information, though it is longer than strictly necessary. The return type outline is helpful but could be trimmed slightly without losing 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?

The description covers key context: lane support, payment requirements, error behavior, and the response structure. With no output schema, it provides a useful return format sketch. It could mention how to handle invalid port codes, but overall it is sufficiently complete for a tool of this 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 coverage is 100%, with each parameter having descriptive text and examples. The description reiterates the container type filter but adds no new parameter semantics beyond what the schema already provides. Baseline 3 is appropriate because the schema carries the load.

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 retrieves certified freight benchmark observations between two ports with optional container type filtering. It explicitly distinguishes these from carrier spot quotes or contracted rates and references a sibling tool for multi-component estimates, 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?

It provides explicit when-to-use guidance by noting these are official published indices, not spot quotes, and directs users to shippingrates_total_cost for multi-component estimates. It also explains behavior on unsupported lanes (empty rates array), which helps set expectations.

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 that already state readOnlyHint, idempotentHint, and destructiveHint, the description discloses the paid nature of the tool ($0.01/call via x402) and the 402 response with payment instructions when unpaid. It also reveals the return object structure, adding significant behavioral context that annotations do not cover.

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

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

The description is concise and well-structured: it starts with the core purpose, adds a usage note, then payment details, and ends with the return shape. Each sentence carries distinct value with no redundancy or 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?

Even without an output schema, the description lists the exact return fields. It also covers payment behavior and error responses. Given the tool's complexity, this is fully sufficient for an agent to select and invoke it correctly, and the context distinguishes it from the many sibling shipping 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?

The input schema has 100% parameter description coverage, with each parameter (country, limit, x_payment) already explained. The description adds no additional parameter-level semantics beyond what the schema provides, so the baseline of 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?

The description uses the specific verb 'Get' and clearly identifies the resource as 'recent shipping regulatory updates and compliance requirements' scoped to a specific country. It distinguishes itself from sibling tools like 'shippingrates_rates' and 'shippingrates_congestion' by focusing on customs regulations, documentation, trade restrictions, and policy changes.

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 provides a clear use case: 'Use this to stay current on regulatory changes that may affect shipments to/from a country.' However, it does not explicitly mention alternative tools or when NOT to use this tool, so it stops short of full exclusionary 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 adds substantial behavioral detail beyond the annotations: it discloses that unpublished metrics remain null ('unpublished carrier delay or sample-size fields remain null'), the payment requirement and 402 error behavior ('PAID: $0.02/call via x402... Without payment, returns 402'), and the return envelope ('Returns the unchanged API reliability envelope with source, period, freshness, and published metric fields'). These traits are not present in the readOnlyHint/idempotentHint annotations, making the tool's behavior highly transparent.

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 four sentences, each earning its place: purpose, usage context, payment terms, and return envelope. It is front-loaded with the primary action and avoids redundancy. The structure is 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 simplicity (read-only, 3 params, no output schema), the description is complete. It covers the data source, null-behavior, payment requirement, error case, and return fields. Combined with full schema documentation and rich annotations, the description leaves no critical gaps for an agent to 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?

The input schema already describes all three parameters with 100% coverage. The description does not add parameter-specific semantics beyond implying that 'line' identifies the carrier. As the schema carries the parameter meaning, the baseline of 3 is appropriate; the description neither enhances nor detracts from parameter 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 opens with a specific verb and resource: 'Get the latest certified public schedule-reliability highlights for a carrier.' This clearly distinguishes the tool from siblings like shippingrates_congestion or shippingrates_stats by focusing on schedule reliability. The resource (carrier) and action (get highlights) are 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?

The description states 'Use this for carrier selection and high-level benchmarking,' providing clear context for when to use the tool. However, it does not explicitly mention alternatives or exclusions, such as when to prefer a different shippingrates tool. This is clear usage context without explicit 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?

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds valuable operational details: unknown inputs contribute zero points, scoring only occurs when a current signal applies, immutable UN/LOCODE chokepoint mapping, payment flow with 402 response, and the exact API result shape. This goes well beyond 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 front-loaded and each sentence earns its place: purpose, scoring logic, chokepoint mapping, alternatives, payment, and return shape. At roughly 100 words it is efficient, but the density requires careful reading, so not quite a 5.

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

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

With no output schema, the description fully specifies the return object shape and includes all critical behavior: scoring conditions, unsupported-route handling, payment flow, and related tools. There are no gaps for an agent to invoke this 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 detailed descriptions and examples for origin, destination, and x_payment. The description adds no per-parameter details beyond the schema, but it does reinforce the UN/LOCODE context. Baseline 3 is appropriate because the schema carries the parameter semantics.

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 ('Get'), a precise resource ('deterministic route-risk score (0-100)'), and clearly scopes the inputs (certified port-congestion measurements, official disruption advisories). It also explicitly names sibling tools for measurements and advisories, differentiating itself from 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 directs users to shippingrates_congestion for exact measurements and shippingrates_congestion_news for advisory detail, establishing when to choose alternatives. It also clarifies behavior for unsupported routes (no result instead of estimate) and the payment requirement, providing clear usage 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 cover read-only, idempotent, and non-destructive hints. The description adds valuable context: it discloses that uncertified families return empty results, legacy rows are not fallback, and provides a structured return shape (query and results categories). It also notes the tool is FREE. These go beyond annotation defaults, earning a 4.

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 compact and front-loaded with the primary action and scope. It then covers behavioral constraints, return format, and related tools in a logical sequence. Every sentence adds distinct value; no filler or 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?

For a one-parameter search tool without an output schema, the description provides sufficient context: what is searched, what is excluded, the result envelope, and sibling alternatives. It could mention result ordering or pagination, but the current detail is adequate for correct 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?

Schema coverage for the single parameter is 100%, but the description enhances meaning by providing concrete examples ('maersk', 'mumbai', 'hapag-lloyd') and clarifying the types of search terms relevant. This guidance helps the agent construct effective queries beyond the schema's generic 'Search term' description.

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

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

The description clearly states the tool's function: 'Search current customer-published ShippingRates datasets by keyword.' It enumerates specific matchable entities (port codes/names, carrier identities, transit services, local-charge names/carriers) and distinguishes itself from siblings by naming dedicated tools for structured lookup. The scope is 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?

The description explicitly provides alternatives: 'Use shippingrates_port for structured port lookup by UN/LOCODE, shippingrates_lines for full carrier listing.' It also implies when not to expect results by stating that uncertified families remain empty and legacy rows are never used as a fallback, guiding the agent on appropriate invocation.

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 the annotations by explaining data source behavior: counts include only certified publishable dependencies, uncertified families report zero instead of falling back to legacy rows, and the distinct nature of countries and shipping_lines counts. It also discloses that the tool is free and provides a return object with a timestamp. This adds valuable context without contradicting the readOnly, idempotent, and non-destructive 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 concise and well-structured. It front-loads the main purpose, then provides usage context, a specific behavior caveat, the return object, and related tools. Every sentence adds value, with no redundant or filler content. The format is easy to scan.

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 there are no parameters and no output schema, the description is highly complete. It specifies the return object structure, the semantic meaning of counts, the timing of usage, and relevant alternatives. It also covers edge cases like uncertified families. This is more than sufficient 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?

There are zero parameters, so the schema provides no semantics. The baseline for 0 params is 4. The description does not need to explain parameters, but it does describe the return fields, which is helpful. Since there are no parameters, the description's value in this dimension is inherently limited; however, it fully compensates by not requiring any parameters and clarifying output.

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 function: 'Get current counts from ShippingRates customer-published datasets.' It specifies the resource and the type of output (counts) and lists the exact fields returned. This distinguishes it from sibling tools, which focus on specific data like rates, lines, or searches.

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

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

Explicit guidance is provided: 'Use this before calling data tools' indicates the optimal timing. Additionally, it names alternatives: 'Use shippingrates_lines for per-carrier breakdowns, shippingrates_search for keyword discovery.' This clearly tells the agent when to use this tool versus related ones.

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, but the description adds crucial context: a paid API with a specific cost ('PAID: $0.02/call via x402') and an exact error condition ('Without payment, returns 402 with payment instructions'). It also discloses the return structure, which is essential given no output 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 concise yet complete: three short paragraphs cover purpose, usage guidance, payment, and return format. Every sentence serves a purpose, and the front-loaded opening makes the tool's function immediately clear.

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 no output schema and only one required parameter, the description provides a full picture: what the tool does, when to use it, payment requirements, error behavior, and the shape of the return array. No critical information seems missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add extra parameter details beyond what the schema provides, but it does contextualize the country/direction filters without needing to repeat enum definitions. This is sufficient.

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 'Get carrier-specific surcharges' and lists specific types (BAF, CAF, PSS, EBS), clearly identifying the tool's function. It distinguishes itself from the sibling tool shippingrates_total_cost by noting that this tool focuses on surcharges only, 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?

Explicit usage context is provided: 'Use this to understand surcharge exposure for a carrier in a specific country/direction.' It also gives a clear alternative: 'For a complete cost breakdown, use shippingrates_total_cost which includes surcharges automatically,' effectively stating when not to use this tool.

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

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

Beyond the readOnly/idempotent annotations, the description adds critical behavioral nuance: the result can be partial, missing components are counted as zero only when reported, and the headline total is mandatory-only. It also explains the mandatory vs. additional cost breakdown, which is not visible in 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 lengthy but every sentence earns its place: main action, caveats, alternatives, payment info, return shape, and a crucial clarification about mandatory vs. additional charges. It is well-organized with clear sections and front-loaded 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?

Given the tool's complexity and lack of an output schema, the description fully compensates by providing a detailed return object shape, explaining the partial-result behavior, and distinguishing between mandatory and additional costs. It also states the payment requirement and 402 fallback, making it complete for an agent to invoke and interpret 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 description coverage is 100% with clear parameter descriptions, so the baseline is 3. The description adds a small but useful connection: it clarifies that detention_days corresponds to 'requested demurrage/detention exposure' and that the result integrates all parameters into a multi-component estimate. This slightly exceeds the schema-only 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 and resource: 'Calculate a published multi-component shipping-cost estimate from certified dependencies', and enumerates the components (freight, surcharges, local charges, D&D, FX, transit). It clearly distinguishes itself from sibling tools by explicitly naming alternatives for individual components.

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 provides explicit when-to-use guidance by stating 'For individual components, use shippingrates_rates, ...' and warns about partial results and the need to inspect coverage flags. It also discloses payment requirements and 402 behavior, which helps the agent decide when to call this 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?

Annotations already declare readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds payment requirements (x402, $0.02/call, 402 on non-payment) and the return array structure, which are valuable behavioral disclosures beyond 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 five sentences, each serving a distinct purpose: main function, usage guidance, alternative tool, payment/costs, and return format. 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?

The tool is simple (3 params, no output schema), but the description compensates by specifying the return array fields, payment behavior, and an explicit sibling. This provides sufficient context for an agent to invoke 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 has 100% parameter coverage with detailed descriptions for origin, destination, and x_payment. The description adds no additional parameter semantics beyond what's already in the schema, so baseline 3 applies.

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

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

Description clearly states the tool gets estimated ocean transit times between two ports, using a specific verb and resource. It distinguishes from sibling shippingrates_transit_schedules by noting this is for quick comparison while the sibling handles detailed routing.

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 'Use this for quick transit time comparison' and directs users to shippingrates_transit_schedules for detailed routing. This provides clear when-to-use and an explicit alternative.

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 destructiveHint=false, so the safety profile is covered. The description adds essential non-obvious behavior: the payment requirement ('PAID: $0.03/call via x402') and the 402 response without payment. It also discloses the return structure. This goes beyond annotations but is not exhaustive (e.g., no rate limits or pagination behavior), so a 4 is appropriate.

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 (about 70 words) and well-structured: purpose sentence, usage guidance, payment note, and return format. Every sentence earns its place, and the most important information (purpose and when to use) is front-loaded. No fluff or 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?

Given the tool's complexity (5 params, no output schema), the description fully covers purpose, usage differentiation, payment constraint, and return structure. The agent has all necessary context to decide when to call and what to expect. The absence of an output schema is compensated by the explicit return array description.

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 does not add new parameter-level detail beyond the schema; it mentions the purpose of routing details but does not elaborate on how to format parameters (e.g., UN/LOCODE format is already in schema). The description does hint at return fields but not parameter semantics.

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 'Get detailed transit schedules for a specific carrier' — a specific verb and resource. It enumerates the exact data returned (service codes, transhipment ports, transit days, frequency) and explicitly distinguishes itself from the sibling tool shippingrates_transit by stating it provides routing details beyond transit time.

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 this tool: 'Use this when you need routing details beyond just transit time...'. It also names the alternative: 'For a quick transit time comparison across all carriers, use shippingrates_transit instead.' This clear guidance leaves no ambiguity.

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 state readOnlyHint, idempotentHint, and destructiveHint, but the description adds valuable behavioral context: it is a PAID endpoint ($0.02/call via x402) and returns a 402 without payment. It also discloses the return format. 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 and front-loaded: it states the primary action first, then usage context, alternatives, payment requirements, and return schema. Every sentence adds unique value, and it is concise without being overly terse.

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?

There is no output schema, so the description appropriately explains the return array structure. It also covers input requirements (port), optional parameters (days_ahead, x_payment), payment behavior, and tool alternatives. For a straightforward read-only tool with good annotations, this is 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?

Schema description coverage is 100%, so the baseline is 3 per the rubric. The description does not add parameter-specific detail beyond what the schema already provides (port examples, days_ahead default). It references the port and days_ahead context implicitly but does not explain parameter formats beyond 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 and resource: 'Get upcoming vessel arrivals and departures at a specific port.' It clearly distinguishes from siblings by explicitly naming shippingrates_transit and shippingrates_transit_schedules as alternatives for other use cases. It also lists the exact data returned, making the tool's 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?

The description gives a clear when-to-use context ('check what vessels are expected at a port — useful for booking planning and tracking') and explicitly names alternative tools for transit time estimates and service-level routing. This provides strong guidance on 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 readOnly/idempotent annotations, it discloses that cutoffs are only returned when published and never inferred, and it clearly describes the paid-call behavior (402 without payment). This adds meaningful operational context without any 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 compact and front-loaded: action, use cases, alternative, payment, and return structure are all covered in a few sentences, with 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 lack of an output schema, the description explicitly documents the return shape (origin, destination, options, coverage). It also covers cutoff behavior, payment, and sibling differentiation, making it fully sufficient for the tool's 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?

All 6 parameters already have descriptive schema text (100% coverage), which establishes a baseline of 3. The description does not add per-parameter details beyond the overall origin-destination scope and the return shape.

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 'Get carrier vessel/voyage schedule options between an origin and destination...' which precisely states the action and resource. It distinguishes itself from the sibling shippingrates_vessel_schedule by explicitly focusing on cutoff deadlines.

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 guidance: 'Use this for booking planning questions that need vessel details, voyage number, transshipment ports, ETA/ETD, and port/SI/VGM cutoffs.' It also names an alternative tool for port-call monitoring without cutoffs and mentions the payment prerequisite.

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