ShippingRates MCP Server

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

Annotations declare readOnlyHint=true and idempotentHint=true, but the description adds crucial behavioral context not covered by annotations: the $0.05 pricing model, the x402 payment mechanism details, and the return data structure ('per-unit handling rates, minimum charges, and storage fees'). This disclosure of monetary cost is essential 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?

The description is well-structured with zero waste: sentence 1 defines the domain, sentence 2 previews returns, sentence 3 states cost requirements, and the Args section documents parameters with examples. Every sentence earns its place and critical information (payment) is front-loaded.

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

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

Given the payment complexity and lack of formal output schema, the description adequately compensates by previewing return values (handling rates, minimum charges, storage fees) and explaining the CFS acronym. The combination of complete parameter documentation (100% coverage), clear behavioral annotations, and cost disclosure provides sufficient context for 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?

With 100% schema description coverage, the baseline is 3. The description adds value by providing concrete example values for the optional parameters: 'import, export' for service and 'general, hazardous' for cargo_type. These examples clarify intended inputs beyond the generic 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 defines the tool's scope: retrieving Container Freight Station handling tariffs specifically for LCL cargo consolidation/deconsolidation at port warehouses. It uses specific verbs ('Get') and distinguishes itself from siblings like shippingrates_rates (general freight) or shippingrates_local_charges by focusing narrowly on CFS warehouse operations.

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 critical usage context by disclosing this is a 'PAID endpoint' costing $0.05 per call with specific payment requirements (x402, USDC on Base/Solana). While it doesn't explicitly name sibling alternatives, the specific domain definition (CFS/LCL handling) combined with the cost warning effectively guides 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?

Excellent addition of cost and payment mechanism details ('PAID endpoint: $0.02 per call via x402') not found in annotations. Annotations already cover idempotency and read-only status. Description also clarifies return data composition ('trend data').

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

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

Well-structured with clear sections: purpose, use case, pricing, Args, Returns. Front-loaded with the core action. No redundant verbosity, though the 'Args:' and 'Returns:' labels are slightly formal for a description field.

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

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

Comprehensive for a paid data retrieval tool: covers purpose, cost mechanism, parameter examples, and return data structure. Acknowledges payment requirement (critical for a paid endpoint). Lacks rate limit details but adequate given no output schema exists.

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 valuable concrete format examples ('INNSA', 'AEJEA') for the UN/LOCODE port parameter that the schema lacks, helping the agent understand the expected input format.

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

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

Clear specific action ('Get') and resource ('port congestion metrics') with detailed sub-components (vessel waiting times, berth occupancy, delays). However, it does not explicitly distinguish from sibling 'shippingrates_congestion_news' or other port-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?

Provides implied usage context ('Useful for assessing port efficiency and planning for potential detention costs'), but lacks explicit guidance on when to choose this over siblings like 'shippingrates_port' or 'shippingrates_congestion_news', or when-not-to-use conditions.

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 safety. Description adds essential behavioral context not in annotations: cost per call, payment method (x402/USDC), and source attribution (7 trade press sources). Does not contradict readOnlyHint.

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

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

Well front-loaded with the core function first. Args section repeats schema info but serves as readable documentation. Payment warning is appropriately prominent. 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?

Handles the unusual payment complexity well with specific cost and currency details. Input parameters are fully covered via schema + Args section. Only gap is lack of description for return values (no output schema exists), though this is partially mitigated by the 'news' framing.

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

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

With 100% schema coverage, baseline is 3. Description adds value by spelling out severity enum values ('normal', 'elevated', 'congested') and clarifying that x_payment is the 'x402 payment proof header'—context that helps the agent understand the payment 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?

Specific verb 'Get' paired with clear resource 'shipping disruption news' and scope '7 trade press sources.' Explicitly mentions coverage areas (Hormuz, Red Sea, Suez) that distinguish it from generic data siblings like shippingrates_congestion.

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 critical pricing constraint 'PAID endpoint: $0.02 per call' which guides usage decisions. However, lacks explicit guidance on when to choose this over sibling shippingrates_congestion (data vs. news articles) or warnings about the 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 declare readOnly/idempotent, but description adds critical behavioral context: explicit pricing ($0.10), payment protocol (x402, USDC on Base/Solana), conditional response ('Returns (when paid)'), and exact JSON return structure including slab breakdown details. Fully discloses the paywall mechanism absent from annotations.

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

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

Well-structured with clear paragraphing: purpose → return preview → payment warning → technical details. Front-loaded with core function. Args section duplicates schema content slightly, but the Returns JSON block efficiently compensates for missing output schema. 'Core tool for logistics cost analysis' signals priority without wasting 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?

Exceptionally complete for a paid endpoint: documents cost, currency, payment method, auth header, and provides full output schema documentation (slabs array, total_cost, currency) despite no formal output_schema field. Domain terminology (D&D, per-diem, free days) explained. Sufficient for 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 coverage is 100% with complete enum listings and descriptions. Description repackages parameters into 'Args' section with explicit enum values (maersk, msc, etc.) and examples (IN, AE, SG), adding minimal new semantics but confirming valid ranges. x_payment description adds 'authenticated access' context linking to payment 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?

Description uses specific verb 'Calculate' with resource 'demurrage and detention (D&D) costs' and defines exact scope (shipping line, country, container type, days). Clearly distinguishes from siblings like shippingrates_inland_haulage (different cost type) and shippingrates_dd_compare (comparison vs. specific calculation) via precise inputs.

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?

Indicates payment requirement ('PAID endpoint: $0.10 per call') and authentication method ('include the payment proof in x_payment'), which are critical prerequisites. However, lacks explicit guidance on when to use this vs. shippingrates_dd_compare or shippingrates_total_cost, though the specific parameter scope implies single-line analysis.

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 confirm read-only, safe operation, but description adds critical behavioral context: explicit cost disclosure ('$0.25 per call'), payment mechanism details ('x402', 'USDC on Base or Solana'), and output format ('side-by-side comparison of D&D costs from all available lines') which compensates for missing output schema. Lacks rate limit or error condition 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?

Well-structured with logical flow: purpose statement → return format → use case → cost warning → parameter details. The Args section repeats schema information but justifies its existence through added examples and contextual linkage ('to compare'). No wasted sentences; cost warning is prominent.

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?

Excellent coverage given constraints. For a paid API endpoint without output schema, description successfully covers: (1) exact cost and payment method, (2) return value structure ('side-by-side comparison'), (3) business context ('freight procurement'), and (4) all parameters with examples. Critical cost information is disclosed upfront.

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?

Despite 100% schema description coverage, the Args section adds meaningful value: provides concrete examples for container_type ('40HC', '20DV') not present in schema enumerations, and contextualizes 'days' as 'detention days to compare'. Clarifies x_payment purpose as header for the payment mechanism described in the main text.

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 uses specific verb-resource combination ('Compare demurrage and detention costs') and clearly scopes the operation ('across multiple shipping lines'). The 'side-by-side comparison' phrase distinguishes this from sibling 'shippingrates_dd_calculate', implying this is for multi-carrier comparison while the sibling likely handles single-scenario calculation.

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

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

Provides clear contextual guidance ('Essential for freight procurement and carrier selection') indicating optimal use cases. While it doesn't explicitly name sibling alternatives to avoid, the 'across multiple shipping lines' scope effectively signals when to choose this over single-line calculation 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 confirm read-only/idempotent safety, but description adds crucial behavioral context: payment requirements ($0.02 per call), payment mechanism details (x402, USDC on Base/Solana), and return value contents (GPS, operator details, capacity) not captured 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?

Well-structured with purpose front-loaded in first sentence, followed by critical payment warning. Args section is redundant given 100% schema coverage but provides readable format. No wasted words or marketing 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?

Excellent completeness for a paid search tool: discloses cost and payment mechanism (essential for paid endpoints), describes return data contents (compensating for missing output schema), and specifies domain scope. No output schema exists, but description adequately covers what to expect.

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 complete descriptions for all 5 parameters. The Args section in the description essentially duplicates schema content without adding semantic depth (e.g., no format examples, validation rules, or business logic beyond the schema definitions). Baseline 3 appropriate for complete 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?

Specific verb 'Search' combined with specific resource 'India ICD/CFS facility directory' and explicit return data scope (GPS coordinates, rail connectivity, operator details, capacity). Clearly distinguishes from rate-focused siblings like shippingrates_rates or shippingrates_transit.

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 critical usage context via 'PAID endpoint' warning and cost ($0.02), plus geographic scoping (India). However, lacks explicit guidance on when to use this versus similar logistics tools like shippingrates_inland_search or shippingrates_port, leaving differentiation implied rather than stated.

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

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

Annotations declare read-only/idempotent/destructive hints, but description adds valuable behavioral context: 'FREE endpoint — no payment required' (cost model) and documents the exact JSON return structure, compensating for the lack of structured 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?

Perfectly structured with front-loaded purpose, domain context sentence, cost disclosure, and clearly delineated Args/Returns sections. No wasted words; every sentence conveys unique information not present in structured fields.

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 2-parameter tool, description is complete: it explains the domain purpose (shipping cost conversion), discloses cost (free), and documents the return payload to compensate for missing output schema. Annotations cover safety profile.

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 minLength/maxLength and examples already defined. Description repeats parameter info with additional examples (INR, AED) but adds no semantic depth beyond the schema's documentation. Baseline 3 appropriate for high-coverage 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 specific verb 'Get' and resource 'exchange rates'. It clearly distinguishes from shipping-logistics siblings (tariffs, ports, vessels) by stating its currency-specific function, while the second sentence bridges to the shipping domain context.

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

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

Provides clear contextual guidance: 'Useful for converting shipping costs quoted in different currencies', establishing when to use it within this shipping-tool suite. Lacks explicit 'when not to use' or named alternatives, though no sibling alternatives exist for FX.

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 critical cost information not in annotations: '$0.08 per call via x402 (USDC on Base or Solana)'. Also discloses output sorting behavior 'cheapest first' and return structure (carrier, mode, weight bracket). Could mention rate limits or cache duration for a 5.

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

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

Well-structured with clear separation: purpose/output description first, payment disclosure second, parameters third. Contains no wasted words. Minor deduction for Args section being somewhat redundant given perfect schema coverage, though the ICD-port pair mention in first sentence adds domain context.

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?

Compensates well for missing output schema by describing return format (sorted rates with specific fields). Includes essential payment context. Would benefit from mentioning error conditions or authentication prerequisites beyond the payment header.

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%, providing full parameter documentation (UN/LOCODE, ICD codes). Description includes an 'Args' section that largely restates schema content without adding semantic enrichment like format examples or validation constraints. Baseline 3 is appropriate given schema completeness.

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?

Specific verb 'Compare' with resource 'inland haulage rates' and scope 'across all carriers for an ICD-port pair'. Distinguishes from sibling 'inland_haulage' by emphasizing the comparative nature across multiple carriers.

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?

Implies usage for rate comparison with 'across all carriers', but lacks explicit guidance on when to use this versus 'inland_haulage' or 'inland_search'. No 'when-not-to-use' or alternative recommendations provided.

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 readOnly/idempotent hints, but description adds critical behavioral context not in structured data: the $0.05 per call cost via x402 payment mechanism and the return value structure (base rate, fuel surcharges, transit times). No contradiction with annotations.

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

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

Description follows logical structure (purpose → returns → cost → parameters). However, the 'Args:' section largely duplicates information already present in the schema (which has 100% coverage), making it redundant rather than concise. Front-loading is good, but duplication wastes tokens.

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 this is a paid endpoint with no output schema, the description adequately covers: payment requirements ($0.05/call), return value composition (rates, surcharges, transit times), and input parameters. Misses error handling or rate limit details, but sufficiently complete for safe 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 is 100%, establishing baseline 3. Description adds valuable concrete examples beyond schema descriptions (e.g., 'INNSA, INMAA' for origin, 'Ahmededabad, Delhi' for destination, '20GP, 40HC' for container types) that help agents understand expected input formats, warranting a score above baseline.

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

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

Description clearly states the tool 'Get[s] inland haulage (trucking/rail) rates' with specific scope 'between ports and inland locations' and clarifies transport modes (trucking/rail). However, it fails to distinguish from siblings like 'shippingrates_inland_search' or 'shippingrates_inland_compare', leaving ambiguity about which inland tool to select.

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?

No guidance provided on when to use this specific tool versus sibling alternatives (shippingrates_inland_search, shippingrates_inland_compare) or prerequisites. While it explains what the tool does, there are no explicit 'use when' or 'for X use Y instead' instructions to aid 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?

While annotations cover read-only/idempotent/destructive hints, the description adds critical behavioral context: the endpoint costs $0.03 per call via x402 (USDC on Base or Solana). This payment requirement is essential operational information not present in structured metadata.

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?

Content is front-loaded with purpose and cost warning, but includes redundant Args section that duplicates 100% of schema parameter descriptions without adding value. Slight redundancy between 'Search for...' and 'Find available...' sentences could be tightened.

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

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

Adequately covers the tool's complexity: explains payment requirements (critical for paid endpoints), hints at return values (haulage options, routes, costs), and documents all 4 parameters. No output schema exists, but description partially compensates by listing expected result types.

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%, establishing baseline 3. The Args section in the description repeats schema definitions verbatim (e.g., 'Shipping line slug', 'ISO 2-letter country code') without adding syntax constraints, format examples, or semantic relationships between parameters.

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

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

Description clearly states the tool searches for inland transport routes (road/rail) and finds haulage options with estimated costs. It identifies the specific verb (search) and resource (inland transport routes), but lacks explicit differentiation from siblings like `shippingrates_inland_compare` or `shippingrates_inland_haulage`.

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?

Implies usage through describing functionality (finding routes from port to final destination), but provides no explicit guidance on when to use this versus sibling tools like `shippingrates_inland_compare` or `shippingrates_search`. The PAID endpoint warning informs cost considerations but not selection criteria.

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

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

Annotations already declare readOnly/idempotent safety. The description adds critical behavioral context not in annotations: the 'FREE endpoint' billing trait, the specific return structure ('Array of shipping lines with country breakdowns'), and scope limitations (only the 6 major lines). 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?

Five sentences, each earning its place: (1) core purpose, (2) specific scope (6 named carriers), (3) data structure details (counts per country), (4) billing constraint (FREE), (5) return type. Front-loaded with the action. 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?

Sufficiently complete for a simple read-only enumeration tool. Compensates for missing output_schema by documenting the return structure ('Array of shipping lines'). Combined with robust annotations covering safety hints, the description provides everything needed for 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?

Zero parameters present (empty schema), establishing a baseline of 4. The description appropriately focuses on return value semantics rather than inventing parameter documentation. With 100% schema coverage of an empty schema, no additional parameter explanation is necessary.

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') with clear resource ('all shipping lines available in ShippingRates') and scope ('per-country record counts'). It distinguishes from siblings by defining its unique purpose: listing carrier metadata (the 6 major lines) with counts, rather than fetching rates, schedules, or tariffs like the other 20+ shippingrates_* tools.

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

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

Provides clear contextual signals for when to use: it exposes the discovery/enum pattern ('Get all shipping lines') and highlights the 'FREE endpoint — no payment required' constraint that differentiates it from potentially paid siblings. Lacks explicit 'when-not-to-use' or sibling name-dropping, but the functional scope implicitly guides 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?

Description adds critical payment behavior ($0.05 per call via x402) and return value structure ('detailed breakdown of all local charges') beyond what annotations provide. Annotations only cover read-only/idempotent safety flags, while description explains the commercial model and response content.

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-sentence structure is perfectly front-loaded: purpose with clarifying examples first, return value second, pricing third. No wasted words. The Args section is cleanly formatted and provides specific context (e.g., 'ISO 2-letter') that augments the schema.

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

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

For a 4-parameter lookup tool with 100% schema coverage and safety annotations, the description is complete. It covers the domain (port local charges), cost model, authentication requirement (x_payment), and return format without needing an 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?

Despite 100% schema coverage (baseline 3), description adds value by providing the concrete example 'INMUN for Mumbai' for port_code and clarifying that x_payment relates to the x402 payment mechanism mentioned in the pricing disclosure. This semantic linking helps agents understand the payment flow.

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 uses specific verb 'Get' with concrete resource examples ('THC, documentation fees, seal fees') that clearly distinguish this from siblings like shippingrates_rates (ocean freight) or shippingrates_inland_haulage. The parenthetical examples immediately clarify what 'local charges' means in shipping context.

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 cost guidance ('$0.05 per call') which is critical usage context for a paid endpoint, but lacks explicit guidance on when to use this versus shippingrates_surcharges or shippingrates_rates. The scope is implied by the examples (THC vs freight) but no alternatives are named.

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

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

Beyond annotations (read-only, idempotent), discloses cost ($0.01/call), payment mechanism (x402 USDC), and exact return structure (coordinates, timezone, facility info). No mention of rate limits or caching prevents a 5.

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

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

Well-structured with clear sections: purpose, returns, pricing, then Args/Returns pseudo-headers. No wasted words, though slightly verbose compared to minimal prose.

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?

No output schema exists, so describing return values in description is required—it documents the full response structure. Payment info, annotations (safety profile), and 2 simple parameters are all adequately covered.

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

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

With 100% schema coverage, baseline is 3. Description adds concrete examples ('INNSA', 'AEJEA') clarifying UN/LOCODE format, and clarifies x_payment is for 'x402 payment proof', exceeding baseline requirements.

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?

Clear specific verb ('Look up') + resource ('port details') + identifier type ('UN/LOCODE'). Distinguishes from rate/calculation siblings by focusing on static port metadata retrieval.

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 critical payment requirement ($0.01 per call) and payment method (x402), but lacks explicit guidance on when to use this vs siblings like shippingrates_search or shippingrates_facilities.

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 readOnly/idempotent hints, but the description adds crucial behavioral context: the explicit cost ($0.03 per call), payment mechanism (x402 via USDC on Base/Solana), return data structure (array with carrier/rate/currency/effective dates), and the inclusion of historical data with trend indicators. This is substantial value 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?

Well-structured with clear sections: purpose statement, return data description, payment warning, and Args documentation. The Args section repeats schema information but adds value through examples. Front-loaded with the most critical info (cost barrier) in the third sentence. Minor deduction for the Returns line being somewhat redundant with the second sentence.

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 paid API endpoint with complex return data, the description adequately covers the critical gaps left by missing output schema (describing the array structure and fields). It acknowledges the payment requirement upfront, which is essential for agent decision-making. Could improve by noting rate freshness or cache behavior, but covers the essentials.

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

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

Although the schema has 100% description coverage (baseline 3), the description adds concrete semantic examples that clarify expected formats: INNSA/AEJEA for UN/LOCODEs and 40HC/20DV for container types. It also contextualizes x_payment as an x402 proof header, linking the payment semantics to the cost disclosure above.

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

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

The description opens with a specific action ('Get ocean freight rates') and clearly defines the scope ('between two ports' with container type). It distinguishes from siblings like shippingrates_inland_compare or shippingrates_congestion by specifying 'ocean freight', which is critical given the 20+ sibling tools in this shipping domain.

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?

While it clearly identifies the domain (ocean freight vs inland), it lacks explicit guidance on when to use this versus siblings like shippingrates_total_cost or shippingrates_dd_compare. It does mitigate this by specifying the resource type (rates between specific ports), but 'when to pay $0.03 vs other endpoints' guidance is missing.

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

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

Description adds critical information absent from annotations: pricing model ($0.01 per call via x402, USDC on Base/Solana) and detailed return structure ('Array of regulatory updates with title, description, effective date, impact level'). Annotations only cover idempotency/safety, not cost or response format.

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

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

Well-structured with clear sections (purpose, coverage, pricing, args, returns). Front-loaded with action and scope. Slight verbosity in repeating parameter types that are in schema, butArgs/Returnssections aid readability.

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?

Excellent for a paid API endpoint. Covers cost mechanism (x402), return structure (despite no formal output schema), and specific regulatory domains served. No output schema exists, yet description fully documents return values, making it 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?

With 100% schema coverage, description adds value through concrete country code examples ('IN', 'AE', 'SG') and confirming default values. Slightly redundant in listing all parameters when schema is complete, but examples provide genuine semantic assistance.

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?

Excellent: 'Get recent regulatory updates and compliance requirements for shipping in a specific country' provides specific verb+resource+scope. Clearly distinguishes from 20+ siblings focused on rates, tariffs, congestion, and schedules by focusing specifically on regulatory/compliance domain.

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?

Clear context through explicit coverage list: 'customs regulations, documentation requirements, trade restrictions, and policy changes.' This positions the tool in the compliance domain vs operational siblings. Lacks explicit 'use X instead' comparison, but domain differentiation is sufficient for 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?

Excellent disclosure beyond annotations: explicitly states this is a 'PAID endpoint' with specific cost ($0.02 per call), payment mechanism (x402), and supported networks (USDC on Base or Solana). Also documents return values ('on-time %, average delay, sample size') compensating for the missing output schema. No contradictions with readOnly/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?

Well-structured with clear sections: purpose → use case → cost warning → arguments → returns. The Args and Returns sections are slightly redundant with the schema but justified given the payment complexity and missing output schema. Every sentence conveys essential information without 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?

Comprehensive for a paid endpoint: covers authentication mechanism (x402), cost structure, parameter details with examples, and return value structure. Since no output schema exists, the explicit description of returned metrics ('on-time %, average delay, sample size') is essential and present.

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

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

With 100% schema coverage, baseline is 3. The description adds value by enumerating the specific shipping line slugs (maersk, msc, etc.) in the Args section and providing concrete examples like 'Asia-Europe' for the trade_lane parameter. It also contextualizes x_payment within the broader payment explanation even though the schema description is identical.

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 specific action ('Get schedule reliability metrics'), the resource (shipping line performance data), and the specific metrics returned (on-time performance, average delays). It effectively distinguishes from siblings like 'shippingrates_transit_schedules' by emphasizing reliability analytics rather than schedule listings.

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

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

Provides clear usage context ('Useful for carrier selection and benchmarking') that signals when to invoke the tool. However, it lacks explicit guidance on when NOT to use it or direct comparisons to siblings like 'shippingrates_transit' or 'shippingrates_stats' that might overlap in functionality.

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 establish read-only/idempotent safety, while the description adds crucial behavioral details: exact pricing ($0.10), payment mechanism (x402), currency/network specifics (USDC on Base or Solana), and response content (composite score range 0-100, specific chokepoint analyses). No contradictions with annotations.

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

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

Well-structured with three distinct blocks: functionality summary, payment warning, and parameter list. Slightly redundant to list args in description when schema is fully documented, but the explicit '(optional)' tag and payment context justify the repetition. 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?

Comprehensive for a paid data retrieval tool: explains inputs (ports), cost mechanism, output content (risk score components), and has strong annotations (idempotent, read-only). Absence of output schema is mitigated by describing the composite score range and data components in the 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 has 100% coverage with basic descriptions. The description adds valuable context that x_payment is 'optional' (though implicit in schema) and explains its purpose as 'x402 payment proof header' tied to the paid endpoint. The origin/destination UN/LOCODE format is confirmed in both schema and 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?

Description clearly states the tool retrieves a 'route risk assessment' with specific components (congestion data, news alerts, chokepoint analysis for Hormuz/Suez/Bab el-Mandeb, composite score 0-100). The specificity of the chokepoints and composite scoring effectively distinguishes this from siblings like shippingrates_congestion or shippingrates_reliability, though it doesn't explicitly name 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?

Excellent disclosure of payment requirements ($0.10 per call, x402 protocol, USDC on Base/Solana) and the optional x_payment parameter. This is critical usage context for a paid endpoint. Minor gap: doesn't explicitly state when to choose this over shippingrates_congestion or shippingrates_reliability, though the feature list implies the superset nature of 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?

Adds valuable context beyond annotations: declares 'FREE endpoint — no payment required' (critical business logic) and details return structure (trade lanes, specific charge types like THC/DO_fee). Annotations already cover safety profile (readOnly/idempotent), so description appropriately focuses on cost and data scope.

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?

Excellent docstring-style structure with clear 'Args' and 'Returns' sections. Information is front-loaded (purpose first) and every sentence serves a distinct function (usage, cost, returns). 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?

Appropriately complete for a single-parameter tool. Compensates for missing output schema by detailing return values (trade lanes, specific charge fees, line info). Cost transparency and exploratory guidance make it self-sufficient.

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

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

Schema has 100% coverage with basic description. The description adds semantic categories ('port, country, or charge type') to the parameter documentation, clarifying what entity types the keyword accepts beyond the schema's generic 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?

States specific verb ('Search') and resource ('ShippingRates shipping data') clearly. Implies distinction from siblings via 'exploratory queries' framing, but does not explicitly contrast with specific lookup tools like 'shippingrates_port' or 'shippingrates_lines'.

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

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

Provides clear positive guidance ('Use this for exploratory queries') with concrete examples (shipping line name, port, country). However, lacks explicit 'when-not' guidance or named sibling alternatives for specific lookups.

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 cover read-only/idempotent safety profile. Description adds significant behavioral context beyond annotations: cost model ('FREE'), data freshness signaling ('last_scrape' field), and complete return structure documentation (JSON example) compensating for lack of formal output schema. 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?

Optimal structure: single sentence purpose statement, bullet-like enumeration of returned counts, usage guidance, cost notice, and return format example. No redundant text; every sentence delivers distinct 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?

Comprehensive for a statistics endpoint. Despite no formal output_schema field, description provides complete JSON return structure with type annotations. Combined with read-only annotations and zero input parameters, the description provides sufficient context for 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?

Input schema contains zero parameters. Per evaluation rules, 0 params = baseline 4. Description appropriately does not fabricate parameter documentation where none exist.

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?

Excellent purpose clarity: specific verb 'Get' + resource 'statistics for the ShippingRates shipping intelligence database'. Lists concrete entities counted (tariff records, ports, trade lanes, etc.) which distinguishes this as a metadata/overview tool vs. operational data retrieval siblings like shippingrates_search or shippingrates_rates.

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

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

Provides clear when-to-use context ('understand the scope and freshness of available data') and valuable cost guidance ('FREE endpoint — no payment required'). Lacks explicit when-not-to-use or named alternatives, though the scope/freshness framing implicitly contrasts with specific query 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 declare safety profile (readOnly/idempotent), so description appropriately focuses on adding cost behavior ($0.02/call, x402 payment mechanism) and return structure (array with amounts/validity periods). No contradictions with annotations.

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

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

Description is efficiently structured with clear sections: purpose statement, return value summary, cost warning, and structured Args/Returns documentation. Every sentence earns its place with no redundant 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?

Despite lacking an output schema, the description adequately documents return values (array structure with type/amount/currency/dates). Combined with payment disclosure and complete parameter coverage, it provides sufficient context for 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 description coverage is 100%, establishing baseline 3. The description duplicates schema information (enum values for line/direction, field descriptions) without adding significant semantic depth beyond what the structured schema already provides.

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

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

The description uses a specific verb ('Get') + specific resource ('surcharges') and clarifies scope with examples (BAF, CAF, PSS, EBS). It clearly distinguishes from sibling tools like shippingrates_rates or shippingrates_local_charges by focusing specifically on surcharge types.

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 critical usage guidance by disclosing the paid nature of the endpoint ($0.02 per call) and payment requirements (x402, USDC). While it lacks explicit comparison to siblings, the specific surcharge examples (BAF, etc.) implicitly guide appropriate use cases.

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

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

While annotations declare the operation is readOnly and idempotent, the description adds critical behavioral context: the $0.15 cost per call, the x402 payment mechanism (USDC on Base/Solana), and the aggregation logic (combining multiple cost categories). It does not mention rate limits or error conditions, preventing a perfect score.

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 logically structured with clear sections for functionality, pricing, arguments, and return values. Every sentence earns its place: the pricing warning is essential for a paid endpoint, and the 'most powerful tool' claim establishes sibling differentiation. The Args/Returns structure is slightly verbose but appropriate for the complexity.

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

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

Despite lacking a formal output schema in the structured metadata, the description provides a comprehensive JSON example in the Returns section detailing all output fields (freight, surcharges, local_charges, detention, transit, total_landed_cost). Combined with the payment disclosure and port examples, this is complete for a 6-parameter paid tool.

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

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

With 100% schema coverage, the baseline is 3. The description adds value by providing concrete examples for ports (INNSA, AEJEA, DELHI) and container codes (40HC, 20DV), and clarifies that x_payment is a 'payment proof header' for the x402 protocol, aiding the agent in parameter construction.

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 'Calculate[s] the full landed cost of shipping a container' with specific components (freight rates, surcharges, local charges, demurrage/detention, transit time). It clearly distinguishes from siblings by noting it 'replaces 5-6 individual queries,' positioning it as an aggregator against the granular sibling tools.

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

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

The description provides clear context for when to use this tool ('most powerful tool,' 'single call replaces 5-6 individual queries'), implying it should be used for comprehensive estimates versus individual component lookups. However, it does not explicitly name the specific sibling tools to use instead (e.g., shippingrates_rates) or explicit exclusion criteria.

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

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

Annotations declare read-only/idempotent/destructive flags, but the description adds critical payment behavior ('PAID endpoint', '$0.02 per call via x402') and authentication requirements ('USDC on Base or Solana') not present in annotations or schema. It also describes the return structure ('Array of transit options with carrier, duration, service type') compensating for the missing 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 well-structured with clear sections (purpose, cost warning, return info, arg details) and front-loads the core purpose. The docstring-style Args/Returns sections are slightly redundant with the schema but necessary given the lack of output schema to document return values.

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 complex domain with 22 sibling tools, the description successfully covers the critical gaps: it explains payment requirements (essential for a paid endpoint), describes return values (since no output schema exists), and provides example codes. It could further clarify differentiation from shippingrates_transit_schedules but remains complete for safe 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?

With 100% schema coverage (baseline 3), the description adds significant value by providing concrete example values for the UN/LOCODE parameters ('INNSA', 'AEJEA'), clarifying the expected format. It also explicitly notes x_payment is optional, which helps with invocation logic.

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 specific action ('Get estimated transit times'), the resource (transit times), and scope (between two ports). It distinguishes from siblings by specifying it returns 'carrier-specific transit durations, service types, and frequencies' rather than generic schedules or other shipping data.

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 warns that this is a 'PAID endpoint' costing '$0.02 per call', which provides cost-based usage guidance. However, it lacks explicit guidance on when to choose this over siblings like shippingrates_transit_schedules or shippingrates_vessel_schedule, leaving the agent to infer based on the return description.

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 read-only/idempotent safety (readOnlyHint=true, destructiveHint=false). Description adds essential financial/operational context: exact pricing ($0.03/call), payment token standard (x402), and blockchain networks (Base or Solana). Missing only rate limit or failure mode 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?

Front-loaded with action and cost warning. However, the 'Args:' section significantly duplicates schema descriptions already present in structured fields; with 100% schema coverage, this repetition is redundantrather than value-add.

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

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

For a 5-parameter paid API, description adequately covers invocation cost, required payment proof parameter, and core functionality. No output schema exists, but the enumerated return fields (service codes, routing, etc.) provide sufficient contract hints.

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%, establishing baseline 3. Description adds concrete examples for carrier parameter ('MAEU', 'maersk') and organizes parameters by requirement level through the Args list structure, clarifying the optional payment header's purpose.

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

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

States specific verb 'Get' with resource 'transit schedules' and enumerates return details (service codes, routing, transhipment ports, frequency). Clearly distinguishes from sibling 'shippingrates_transit' and 'shippingrates_vessel_schedule' by specifying carrier-specific detailed 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?

Discloses critical cost constraint ('PAID endpoint: $0.03 per call') and payment mechanism (x402, USDC on Base or Solana), which guides invocation timing. However, lacks explicit guidance on when to use versus sibling tools like 'shippingrates_transit' or 'shippingrates_vessel_schedule'.

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 readOnly/idempotent/safe profile. Description adds crucial behavioral context: monetary cost per invocation and return value structure ('Array of vessel arrivals/departures...') since no output schema exists. 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?

Excellent structure with clear visual separation: purpose statement, pricing warning, Args section, and Returns section. No wasted words; the em-dash and formatting choices improve scannability. Appropriate length for complexity.

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

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

Thoroughly complete given constraints. Compensates for missing output schema by documenting return structure. Covers payment requirements (critical for this paid endpoint). With only 3 parameters (1 required) and clear annotations, description provides sufficient context for 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 is 100%, establishing baseline 3. Description adds value by providing concrete port code examples ('INNSA', 'AEJEA') for the UN/LOCODE format, but otherwise mirrors schema descriptions without adding syntax constraints or validation rules 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?

Specific verb 'Get' with clear resource 'vessel schedules' and explicit scope 'upcoming...at a port'. The description distinguishes from siblings like shippingrates_transit_schedules by specifying port-level arrivals/departures rather than route transits.

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 critical cost information ('PAID endpoint: $0.02 per call') and payment mechanism (x402, USDC on Base/Solana) that governs usage decisions. Lacks explicit differentiation from sibling shippingrates_transit_schedules, though the port-centric framing provides implicit context.

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