ShippingRates MCP Server (Apify)

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

Discloses payment requirement ($0.05/call via x402) and 402 error response. Annotations already indicate readOnly and idempotent, but description adds critical cost and error behavioral context.

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

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

Three concise paragraphs: definition, usage guidance, payment/return format. No unnecessary sentences.

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 purpose, usage, return format (no output schema), and payment. Complete and self-contained.

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

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

Schema coverage is 100%, so baseline 3. Description adds value by explaining port parameter with examples and the return structure, but does not detail all parameters 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 it retrieves CFS handling tariffs for LCL shipments, distinguishing from FCL. Specific verb 'get' and resource 'CFS handling tariffs'. Sibling differentiation by excluding FCL.

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 for LCL shipments to estimate warehouse costs, and not relevant for FCL. Provides clear context but does not name specific alternative tools among siblings.

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

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

Adds substantial behavioral context beyond annotations: null/unknown handling for unpublished fields, current certified denominator (USLAX), payment requirement with 402 response, and the exact return envelope format. Highlights idempotent/read-only nature already in annotations, with 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?

Four sentences are front-loaded with purpose, then cover data behavior, alternative, payment, and return structure. Every sentence earns its place 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?

Covers purpose, data semantics, payment constraints, alternative tool, and return envelope. Annotations provide safety profile, and description fills all remaining contextual gaps for 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?

Schema covers 100% of parameters with descriptions. The tool description reinforces the port parameter's USLAX denominator and gives context to x_payment, but it does not introduce new parameter-level details 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?

Description opens with a specific verb+resource+scope: 'Get certified port-authority congestion measurements for a specific port.' It clearly distinguishes from the sibling tool shippingrates_congestion_news by directing disruption advisory use there.

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 (certified measurements) and when not to (disruption advisories → shippingrates_congestion_news). Also discloses the paid nature and payment failure behavior, 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?

Beyond the annotations (readOnlyHint, idempotentHint), the description discloses important behaviors: it uses only explicit operational-disruption terms, returns an empty array instead of inventing alerts, and requires payment via x402 with a 402 response if unpaid. It also specifies the source limitation to Port of Rotterdam and Port of Los Angeles, which is not in the annotations.

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

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

The description is structured in four short paragraphs, front-loading the core purpose and then adding alternatives, payment, and output details. It contains no filler, though it is somewhat dense. Each sentence earns its place, but it could be slightly more compact for a read-only fetch tool.

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

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

Given there is no output schema, the description compensates by listing the exact returned fields: { headline, summary, source, port_code, severity, published_at }. It also covers payment behavior, source restrictions, empty-result semantics, and sibling tool distinctions, making the tool's behavior well-specified 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 description coverage is 100% with all five parameters documented, so the baseline is 3. The description does not add additional parameter semantics; it only references the output fields (headline, summary, etc.) which include some of the parameter names in context. No further elaboration on parameter usage or syntax 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?

The description opens with a clear verb+resource: 'Get certified shipping-disruption publications from reviewed official port-authority sources.' It explicitly distinguishes from siblings by directing users to shippingrates_congestion for quantitative measurements and shippingrates_risk_score for risk scoring, which clarifies what this tool uniquely provides.

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 alternatives: 'For quantitative measurements, use shippingrates_congestion. For route-level risk scoring, use shippingrates_risk_score.' It also provides usage context such as the payment requirement and the tool's behavior on empty results, giving clear guidance on when and how to invoke it.

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

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

Annotations already declare readOnly/non-destructive/idempotent, and the description adds substantial behavioral context: no false $0 responses, live-derived lane coverage in errors, charge-type priority defaults, and the x402 payment requirement with 402 response on non-payment. 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 organized into clear paragraphs with front-loaded purpose, but it is somewhat wordy (e.g., the 'live from the database... go stale' clause could be trimmed). All content is relevant, though a few phrases are redundant.

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 7 parameters, no output schema, and payment/coverage edge cases, the description provides a complete picture: return field names, error behavior, storage caveats, and payment flow. It would be improved only by a structured output schema, but as a description it fills that gap adequately.

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 elevates this by explaining charge_type semantics (terminal storage vs carrier D&D, only returned when explicitly requested) and the payment header requirement. It also clarifies the default detention→demurrage→combined priority, adding meaning beyond enum values.

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 demurrage and detention (D&D) costs for one carrier in one country.' It further clarifies scope (detailed cost breakdown, free days, per-diem rates, total cost) and explicitly distinguishes from the compare sibling, making selection 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 ('Use this when the user needs a detailed cost breakdown for a specific carrier') and names the alternative for multi-carrier comparison (shippingrates_dd_compare). It also covers conditional usage for storage via charge_type and outlines the no-data error expectation, giving the agent clear decision rules.

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 readOnlyHint, idempotentHint, destructiveHint. Description adds crucial behavioral info: payment requirement ($0.25/call via x402), 402 response without payment, and return format (array of objects sorted by total_cost). 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?

Every sentence serves a purpose: purpose, use case, alternative, pricing, return format. Concise and well-structured, 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 simple inputs and no output schema, the description fully covers what the tool does, when to use it, payment, and return structure. Adequate for an agent to invoke 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% (all 4 parameters described). Description does not add extra meaning beyond the schema. 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 clearly states the verb 'compare' and the resource 'demurrage and detention costs across ALL available carriers' with specific scope (same country, container type, days). It distinguishes from sibling tool shippingrates_dd_calculate for single carrier breakdown.

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 freight procurement and carrier selection' and provides when-not-to-use: 'For a single carrier's detailed D&D breakdown, use shippingrates_dd_calculate instead.' Clear context and 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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses important behavioral traits: the free-time clock starts at a carrier-defined event, arrival_date is taken as supplied with data_basis='user_supplied_arrival', the response's charge_family field always discloses which charge type answered, and the tool requires payment via x402 returning 402 if unpaid. These contextual details go well beyond annotations and provide 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?

The description is information-dense yet well-structured: it opens with the core function, then provides usage guidance, alternative mode, payment requirement, and return fields, all in a logical flow. Every sentence adds value—there is no filler or repetition, and the structure makes the content 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?

With no output schema, the description lists the exact return fields (free_days_total, days_elapsed, free_days_remaining, etc.), which fully compensates. It also covers edge cases like storage coverage limitations, payment failures (402), and the data_basis and charge_family fields. For a tool with 8 parameters and several nuanced behaviors, the description is comprehensively complete.

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

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

The schema already covers 100% of parameters with descriptions, earning a baseline of 3. The description adds valuable semantics for charge_type—clarifying that 'storage' is a distinct terminal charge, only returned when explicitly requested, with thin coverage and an explicit error listing covered lanes—and explains arrival_date as the clock-starter with user-supplied data basis. This added context justifies a score above baseline, though not every parameter receives additional explanation.

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 ('report') with a clear resource (free-time countdown) and specifies the required inputs (carrier, country, container type, arrival date). It explicitly distinguishes itself from the sibling tool shippingrates_dd_calculate, which answers a fixed number of days, making this the proactive countdown 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?

The description directly states when to use the tool ('Use this to answer "how long until this container starts costing demurrage, and how much per day?"') and contrasts it with shippingrates_dd_calculate, noting they share the same engine so numbers agree. It also provides explicit guidance on using charge_type='storage' for terminal storage, with coverage caveats.

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. The description adds valuable context beyond that: it discloses that optional operational attributes (GPS, rail, operator, capacity) are null unless separately certified, and explains the payment requirement ($0.02/call) and 402 response if not paid. This rich behavioral detail fully leverages the annotation baseline.

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, followed by usage, payment, and response shape. However, the point about optional attributes being null is repeated in both the second and fourth paragraphs, creating minor redundancy. Overall it is concise and well-structured.

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 absence of an output schema, the description helpfully explains the return shape: 'certified code/name/type and null for unsupported optional attributes'. It also covers payment edge cases. While it doesn't mention pagination or list vs. single response, the existing response shape reference is enough for this 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% and every parameter has a clear description in the schema. The tool description does not add extra parameter-level semantics beyond that, 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 opens with a clear verb 'Search' and names the specific resource: 'India's current official ICEGATE Inland Container Depot (ICD) and Container Freight Station (CFS) directory'. It also states search criteria (code, name, type), fully differentiating it from sibling tools like shippingrates_cfs_tariffs or shippingrates_inland_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 states 'Use this to resolve an official ICEGATE ICD/CFS code or facility name', giving clear direction on when to invoke. It also sets expectations that unsupported attributes remain null, preventing misuse for GPS/rail data. It doesn't name specific alternatives, but the guidance is sufficient.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the tool's safety profile is known. The description adds valuable behavioral context: the ECB publication update frequency, the fail-closed behavior for unsupported currencies, the fact that it's free, and the exact return fields including cache_age_minutes. This goes beyond the annotations and sets clear expectations.

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 that efficiently pack purpose, use case, update schedule, failure behavior, cost, and return format. It is front-loaded with the main action and every sentence serves a purpose. The 'Returns' line is a helpful structured addition. It could be slightly tighter, but it's well-organized and 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?

Despite having no output schema, the description explicitly lists the return fields: rate, from, to, source, fetched_at, cache_age_minutes. It also covers update frequency, fail-closed behavior, and cost. For a simple two-parameter, read-only tool with rich annotations, this is fully complete — the agent has everything needed to invoke it and interpret the result.

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

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

The input schema covers 100% of the parameters with descriptions and examples, so the baseline is 3. The description adds a list of supported currency codes (USD, EUR, INR, SGD, CNY, JPY) and mentions the 'official ECB daily series,' which gives a bit more context. However, this is marginal since the schema already indicates 3-letter codes with examples.

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 the current certified ECB reference rate between two supported currencies.' This clearly differentiates the tool from every sibling tool, since none of the other shippingrates_* tools handle currency conversion. The scope is well-defined and 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 states when to use this tool: 'useful for converting shipping costs quoted in different currencies' and 'Use this to normalize costs from different carriers/countries to a common currency for comparison.' It does not explicitly mention alternatives or exclusions, but since it is the only FX tool among the siblings, the use case guidance is clear 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 indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds context: sorted by rate ascending, payment requirement, and that ramp and door rates are never mixed. 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?

Approximately 120 words, well-structured with clear sections. Front-loaded with main purpose. No redundant sentences.

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 8 parameters, payment requirement, and no output schema, the description covers functionality thoroughly. It lists return fields, sorting, and mode exclusion. Very complete for agent 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 description coverage is 100%. Description adds value by explaining defaults (delivery_mode default 'ramp', cargo_class default 'general'), clarifying that ramp and door are not mixed, and providing examples for origin (UN/LOCODE).

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 compares inland haulage rates across all carriers for a port-to-ICD/city pair, sorted cheapest first. It distinguishes from sibling tools 'shippingrates_inland_haulage' (single carrier) and 'shippingrates_inland_search' (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?

Explicitly states when to use (carrier selection, cheapest rate) and when not (for single carrier rates, use shippingrates_inland_haulage; to discover routes, use shippingrates_inland_search). Also mentions payment requirement ($0.08/call via x402) and behavior if not paid (returns 402).

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, indicating a safe read operation. The description adds critical behavioral context: payment requirement ('PAID: $0.05/call via x402... Without payment, returns 402 with payment instructions') and return format (array of fields). 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 concise (5 sentences) and well-structured: purpose first, then usage guidance, sibling differentiation, payment info, and return fields. 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 8 parameters (all described in schema), no output schema but return fields listed, and coverage of usage, payment, and return format, the description is fairly complete. Slight deduction for not mentioning pagination or error handling, but overall it's clear and sufficient.

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

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

Schema description coverage is 100%, so the description adds minimal value beyond what the schema already provides. The description mentions return fields but does not clarify parameter usage beyond the schema. Baseline score 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 clearly states the tool's purpose: 'Get inland haulage (trucking/rail) rates for moving containers between a port and an inland location.' It specifies the verb (get), resource (inland haulage rates), and scope (port to inland). It distinguishes from sibling tools by referencing related tools for route discovery and comparison.

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: 'Use this when you know the specific origin port and destination and need rate quotes.' It also provides clear alternatives: 'To discover what routes exist first, use shippingrates_inland_search. To compare rates across all carriers for the same route, use shippingrates_inland_compare.'

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

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

Annotations already mark readOnly, idempotent, and non-destructive. The description adds key behavioral context: the paid $0.03/call requirement via x402, the 402 response when unpaid, and 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 front-loaded and compact, with clear sections for usage, alternatives, payment, and return format. Minor redundancy between 'Returns route options...' and 'Returns: Array of...' but no wasted sentences.

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 explicitly defines the return array shape { origin, destination, mode, container_types, icd_code }. It also covers payment/error behavior and lists sibling alternatives, making it sufficient for a 6-parameter tool with 100% schema coverage.

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-world usage context: the 'ahmedabad' example showing how the keyword maps to a route from Nhava Sheva, and the expected route fields (ICD/CFS codes, container types). This goes beyond the schema by illustrating query behavior.

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

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

The description starts with a specific verb+resource: 'Search for available inland transport routes (road/rail haulage) from port to inland destinations for a specific carrier.' It clearly differentiates from sibling tools by naming shippingrates_inland_haulage and shippingrates_inland_compare for quote and comparison.

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?

'Use this to discover what haulage routes a carrier offers in a country... For actual haulage rate quotes, use shippingrates_inland_haulage. For cross-carrier rate comparison, use shippingrates_inland_compare.' This explicitly states when to use the tool and names 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?

Annotations already cover readOnly, idempotent, and non-destructive traits. The description adds value by disclosing that the tool is free ('FREE — no payment required') and clarifying the scoped nature of the data (reviewed shipping lines with live D&D coverage), which goes 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 concise and well-structured: first sentence states the core function, second gives usage context, third notes the free aspect, fourth specifies the return format, and fifth points to related tools. Every sentence earns its place 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?

For a zero-parameter, read-only listing tool, the description is complete. It covers what it lists, why you'd use it, the cost (free), the return structure, and relationships to sibling tools. There is no output schema, but the description fills that gap by explicitly naming the return fields.

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 correctly explains what is returned (Array of { shipping_line, country, records }), which provides semantic meaning for the tool's output without needing 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 a specific verb ('List') and a specific resource ('reviewed shipping-line identities that currently have live D&D coverage, with per-country record counts'). It distinguishes itself from sibling tools by explicitly mentioning alternatives for aggregate totals and keyword-based 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?

It provides explicit when-to-use guidance ('Use this to discover which carrier-country D&D combinations are currently available before querying a tariff tool') and names related tools (shippingrates_stats, shippingrates_search), giving clear context for 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?

Goes beyond annotations by disclosing payment requirements ($0.05/call via x402, 402 response on non-payment) and the response structure (array of charge objects). Annotations already declare readOnly/idempotent, and the description adds valuable operational details without contradiction.

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

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

The description is compact and well-structured with clear sections: purpose, usage, payment, and returns. Every sentence adds 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?

Despite having no output schema, the description fully explains the return format (array of charge objects with fields). It covers purpose, usage, payment, and output, making it complete for the tool's complexity and 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 description coverage is 100%, so the baseline is 3. The description does not add extra parameter-level semantics beyond what the schema already provides; it merely restates the tool's purpose. No additional meaning is given to line, country, port_code, or x_payment 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 explicitly states the tool's function: 'Get local charges at a port for a specific carrier' and enumerates the charge types (THC, BL/DO, seal fees). It clearly distinguishes the tool from siblings by focusing on port-local charges rather than broader rate calculations.

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

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

Provides explicit usage context: 'Use this when calculating total shipping costs at origin or destination.' It names specific alternatives and complementary tools (shippingrates_dd_calculate, shippingrates_total_cost), giving clear guidance on when to use this tool versus others.

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 disclosing payment requirements ($0.01/call, payment method, and 402 response without payment). This adds important behavioral context that annotations do not cover. No contradictions with annotations (readOnlyHint, idempotentHint, destructiveHint 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 concise, with the main action front-loaded. Every sentence adds value: purpose, usage guidance, payment info, and return format. 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?

Given the tool's simplicity (2 parameters, no output schema), the description is complete. It covers purpose, usage, payment, and return fields. It also differentiates from sibling tools effectively.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by providing example UN/LOCODE values and clarifying that the x_payment parameter is for payment proof, enhancing understanding beyond the schema alone.

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: look up port details by UN/LOCODE, including specific fields like name, country, coordinates, timezone, and facilities. It distinguishes itself from sibling shippingrates_search by advising to use that tool if the code is 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?

The description explicitly tells when to use this tool (validate port codes, get port metadata) and when not to (if UN/LOCODE is unknown, use shippingrates_search first). This provides clear context and alternative 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavior beyond annotations: unsupported lanes return empty arrays, unpaid calls return 402 with payment instructions, and the return payload includes detailed fields such as rate_low/mid/high and trend. 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 relatively long, but it is well-structured with a clear opening purpose, distinguishing clarifications, payment info, and a detailed return format. The return structure is necessary because no output schema is provided. Each sentence adds value, though a tighter format could 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 no output schema, the description fully compensates by detailing the return object and nested rates array fields. It covers edge cases (empty array, 402), differentiates from siblings, and provides operational requirements (payment). This is a complete description for a tool of this complexity with four parameters and no 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%, with each parameter having a description and examples for origin and destination. The description only adds the phrase 'optionally filtered by container type,' which mirrors the schema. It does not introduce new parameter semantics beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description opens with a specific verb+resource: 'Get current certified freight benchmark observations between two ports, optionally filtered by container type.' It clearly distinguishes this from carrier spot quotes and contracted rates, and contrasts with sibling shippingrates_total_cost. The scope is precise and the tool's identity as a benchmark lookup 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 states when to use this tool versus alternatives: 'For a published multi-component estimate, use shippingrates_total_cost.' It also clarifies that these are official indices, not spot quotes, and that unsupported lanes return an empty rates array. Payment requirements are disclosed, giving clear operational context.

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

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

The description discloses two important behavioral traits beyond the annotations: the paid x402 payment requirement ($0.01/call with failure response 402 and payment instructions) and the exact return payload shape. Since annotations already declare readOnlyHint and idempotentHint, the description adds practical operational and failure-mode 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 organized into clear, purposeful sections: purpose, usage, pricing, and return format. Every sentence contributes useful information, and there is no fluff. It is slightly longer than a minimal two-sentence description but remains efficient given the need to cover the payment and output structure.

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 provides the exact return field structure (updates array with 9 subfields). It also covers payment failure mode and purpose. It could optionally describe pagination or error handling beyond the 402, but for a read-only tool with strong annotations, this is sufficient.

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

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

The input schema has 100% description coverage for all three parameters (country, limit, x_payment), so the schema already documents their meaning and constraints. The description adds context about the payment flow but no additional parameter-level semantics. Therefore a 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 opens with a specific verb ('Get') and resource ('recent shipping regulatory updates and compliance requirements') scoped to a specific country. It clearly distinguishes the tool from siblings like `shippingrates_cfs_tariffs` and `shippingrates_congestion` by naming the domain (customs, documentation, trade restrictions, 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?

The second line explicitly says 'Use this to stay current on regulatory changes that may affect shipments to/from a country.' This provides a clear situational trigger. It doesn't explicitly list when not to use it, but the specificity of the tool and siblings makes the intended context obvious.

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 readOnlyHint/idempotentHint annotations, it discloses critical behaviors: payment requirement with $0.02/call and 402 response without payment, nulls for unpublished metrics, and return envelope structure (source, period, freshness, published metrics).

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?

Four sentences, front-loaded with the core purpose, then concise use guidance, payment notice, and return envelope description. 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?

For a simple read-only tool with one required parameter, the description covers use case, payment, null behavior, and return envelope—sufficient despite no 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 descriptions cover all three parameters with 100% coverage, so the description doesn't need to add param-level detail. It adds minimal value beyond the schema, but no gaps.

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 'gets the latest certified public schedule-reliability highlights for a carrier' and frames it for carrier selection and high-level benchmarking, distinguishing it from sibling tools focused on rates, congestion, transit, etc.

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 context for usage ('Use this for carrier selection and high-level benchmarking'), but doesn't mention specific alternatives or when-not-to-use scenarios.

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 deterministic scoring, zero contribution for unknown inputs, conditional scoring only when at least one signal applies, immutable UN/LOCODE mapping, payment requirement (returns 402 without payment), and the unchanged API result shape. No contradictions with annotations.

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

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

The description is well-structured into three concise paragraphs: purpose and data sources, input behavior and alternatives, and payment/return shape. Every sentence carries essential information and avoids redundancy, making it 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?

For a tool with no output schema, the description fully specifies the return object shape, payment terms, error behavior (402 + instructions), and edge cases (unsupported routes return no result). Combined with rich annotations, the description covers all necessary context 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?

Schema coverage is 100%, so the schema already defines parameters with examples. The description adds behavioral semantics for inputs: 'Unknown inputs contribute zero points' and the chokepoint mapping for specific UN/LOCODE locations, which goes beyond the schema's basic type/length constraints.

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 a deterministic route-risk score (0-100) from current certified port-congestion measurements and explicit official disruption advisories.' It clearly distinguishes the tool from siblings by mentioning exact measurements and advisory detail tools, and states the exact output fields.

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: 'For exact measurements, use shippingrates_congestion. For advisory detail, use shippingrates_congestion_news.' It also states when no result is returned (unsupported routes) and the payment prerequisite, giving clear when-to-use versus 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 readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds valuable behavioral context beyond annotations: 'Uncertified families remain empty and legacy rows are never used as a fallback' clarifies data coverage limits, and 'FREE — no payment required' discloses cost. It also outlines the return structure, though it does not detail pagination or rate limits.

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 information-dense, covering purpose, match targets, behavioral constraints, cost, return format, and related tools in six sentences. There is minor redundancy ('FREE — no payment required' repeats the word free), but no wasted detail.

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 remarkably complete for a simple search tool. It explains the data scope, limitations, cost, return shape, and alternative tools. Despite lacking an output schema, it explicitly lists the return object structure. Sibling tools are numerous, but the description helps disambiguate by referencing the most relevant alternatives.

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% as the single parameter 'keyword' has a description with examples. The description adds semantic meaning by explaining what the keyword matches (certified port codes/names, reviewed carrier identities, published transit services, local-charge names/carriers), which helps the agent choose effective search terms.

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 specifies the resource (customer-published ShippingRates datasets), the action (search), and the scope (matching certified port codes/names, reviewed carrier identities, published transit services, and local-charge names/carriers). It also distinguishes from siblings by explicitly naming related tools for structured 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 usage guidance by naming alternatives: 'Use shippingrates_port for structured port lookup by UN/LOCODE, shippingrates_lines for full carrier listing.' It also includes a when-not-to-use signal: 'Uncertified families remain empty and legacy rows are never used as a fallback,' implying this tool is only suitable for certified/published data.

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

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

The description adds valuable behavioral context beyond the annotations (readOnly, idempotent, non-destructive). It specifies that counts include only certified publishable dependencies and that uncertified families report zero instead of falling back to legacy data. It also discloses the free nature ('FREE — no payment required') and explicitly lists the return shape. These traits are not present in the annotations and significantly aid the agent in understanding side effects and interpretation.

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 comprehensive. It front-loads the core purpose, then provides usage guidance, a critical behavioral caveat, return structure, and related tools. Each sentence earns its place; there is no fluff or redundancy. The structure flows logically from purpose to usage to details.

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

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

Given that the tool has no parameters and no output schema, the description compensates fully. It specifies the exact fields returned, the source and semantics of counts, when to use it, and related alternatives. This is complete enough for an agent to invoke and interpret the results without further documentation.

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

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

The tool has zero parameters, so the schema coverage is effectively 100% and there is no parameter semantics to add. The description does not need to explain any parameters. Per the rubric, the baseline for 0 params is 4. No deductions are warranted; the description appropriately omits parameter 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 current counts from ShippingRates customer-published datasets.' It clearly defines the tool's scope and differentiates it from siblings by naming alternatives in the final sentence: 'Use shippingrates_lines for per-carrier breakdowns, shippingrates_search for keyword discovery.' This makes the purpose unambiguous and distinct from 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?

Explicit usage direction is provided: 'Use this before calling data tools.' This tells the agent when to invoke this tool in a workflow. Additionally, it states alternatives for specific needs, e.g., 'shippingrates_lines for per-carrier breakdowns, shippingrates_search for keyword discovery.' This fully addresses when-to-use vs 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the base safety profile is covered. The description adds valuable operational context: the $0.02/call payment requirement via x402, and the 402 response without payment. It also discloses the return format. 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 four sentences, front-loaded with the main purpose, then usage, payment, and return format. Every sentence earns its place with no wordiness.

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 includes the purpose, usage context, payment requirement, failure mode, and return array structure. With annotations covering read-only/idempotent behavior and the schema covering parameters, this is nearly complete. It could optionally mention when country/direction are optional, but the schema already handles that.

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 reinforces that country and direction are relevant ('in a specific country/direction'), but it does not add new semantic detail beyond the schema's parameter 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 'Get carrier-specific surcharges' — a specific verb and resource — and enumerates surcharge types (BAF, CAF, PSS, EBS). It also distinguishes itself from shippingrates_total_cost by noting that tool includes surcharges automatically. However, it does not differentiate from other surcharge-related siblings like local_charges or 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?

Explicitly states when to use: 'Use this to understand surcharge exposure for a carrier in a specific country/direction.' It also names an alternative: 'For a complete cost breakdown, use shippingrates_total_cost which includes surcharges automatically.' This provides clear context and exclusions.

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

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

With annotations only indicating read-only, idempotent, and non-destructive behaviors, the description significantly adds transparency: it discloses partial results, explains when missing components count as zero, details the mandatory vs. additional charge breakdown, and even mentions the payment requirement and 402 error. This goes far beyond the annotation hints and provides critical behavioral context.

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

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

Although lengthy, every sentence earns its place: it front-loads the core action, then covers critical caveats, return structure, and an important accounting rule. The structure is logical, with the 'IMPORTANT' note appropriately highlighted. No redundancy is present.

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

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

Given the tool's complexity, the description is remarkably complete: it details the return object components, explains the meaning of 'verified', 'coverage', and 'data_gaps', quantifies payment, and clarifies mandatory vs. additional cost calculations. Without an output schema, the description fully compensates by specifying the return structure and semantics.

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 context by linking 'detention_days' to 'requested demurrage/detention exposure' and clarifying that the total includes 'requested D&D', which is not explicit in the parameter schema. While the schema already documents each parameter, this semantic linkage provides extra meaning, 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 clearly states the tool 'Calculate a published multi-component shipping-cost estimate' from certified dependencies, which is a specific verb+resource. It further distinguishes itself from siblings by explicitly listing component-specific tools, leaving no ambiguity about its overall function.

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 by stating 'For individual components, use shippingrates_rates, shippingrates_surcharges, shippingrates_local_charges, and shippingrates_dd_calculate.' It also clarifies the interpretation context ('A market index is not a carrier quote') and instructs users to inspect fields before quoting, effectively covering both usage and exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the tool's safety is transparent. The description adds critical behavioral details beyond annotations: payment requirement ($0.02/call via x402), the behavior on failed payment (returns 402 with instructions), and the return format (array of fields). 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?

Three concise paragraphs: first states the main function, second provides usage guidance, third covers payment and return format. No redundant sentences, well-organized, and front-loaded with the essential purpose.

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

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

Given there is no output schema, the description adequately describes the return format (array of carrier, transit_days, etc.). It also covers payment details and distinguishes from sibling. For a simple two-parameter tool, this is complete and leaves no critical 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 all three parameters described in the input schema. The description does not add significant new meaning about parameters beyond what the schema provides, but it contextualizes the tool's response. Baseline 3 is appropriate as schema does the heavy lifting.

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 verb ('Get'), resource ('estimated ocean transit times'), and scope ('between two ports across all available carriers'). It also distinguishes from the sibling tool 'shippingrates_transit_schedules' by specifying that this is for quick comparison vs detailed routing, establishing a distinct 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 this tool ('for quick transit time comparison between ports') and when not to use it, directing to an alternative for detailed routing with transhipment ports and service codes ('use shippingrates_transit_schedules instead'). Clear context and exclusion.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: payment requirement ($0.03/call), error handling (returns 402 without payment), and the return structure (Array of objects with specific fields), 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 concise with 5 sentences: purpose, usage guidance, payment info, return structure. It is front-loaded with the primary purpose and well-structured 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?

The description covers purpose, usage guidance, payment, and return format. Without an output schema, it provides enough context. However, it lacks mention of behavior when no schedules are found (e.g., empty array), which would improve completeness.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description does not add parameter-specific semantics beyond what the schema provides, but it does contextualize the output. 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 specifies the verb 'Get', the resource 'detailed transit schedules', and the details included (service codes, routing via transhipment ports, transit days, sailing frequency). It also distinguishes from the sibling tool shippingrates_transit, which is for quick transit time comparison.

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 ('when you need routing details beyond just transit time') and when not ('For a quick transit time comparison across all carriers, use shippingrates_transit instead'), with clear alternatives.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds payment requirement and 402 response behavior, which is beyond annotations and valuable for agent decision-making.

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?

Concise two-paragraph structure with front-loaded purpose, efficient use of words, no 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?

Despite no output schema, description enumerates return fields, covers payment context, and no missing information for this 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?

Schema has 100% coverage with descriptions. Description reinforces default for days_ahead (14) and explains x_payment header usage, adding clarity 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?

Description clearly states 'Get upcoming vessel arrivals and departures at a specific port' with specific verb+resource. It differentiates from sibling tools shippingrates_transit and shippingrates_transit_schedules.

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 this tool for booking planning and tracking, and when-not to use it, referencing alternatives for transit times and detailed routing.

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

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

Annotations already indicate readOnly and idempotent. Description adds critical context: missing cutoffs remain null (no inference), payment requirement ($0.03/call) and 402 error handling. 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?

Concise, front-loaded with purpose, then usage, payment, and return format. Every sentence adds value; no 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?

Despite missing output schema, description provides a detailed return structure. Also covers error behavior and payment context, fully addressing the tool's usage requirements.

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?

Input schema has 100% description coverage, so parameters are well-documented. Description adds no new semantic meaning beyond the schema, meeting the baseline expectation.

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 vessel/voyage schedule options with cutoffs, using specific verb+resource. It distinguishes from the sibling tool shippingrates_vessel_schedule which lacks cutoff details.

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: 'for booking planning questions that need vessel details...cutoffs.' Also provides clear alternative: 'For port-call monitoring without cutoff details, use shippingrates_vessel_schedule.'

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