FreightGate MCP Server

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

Annotations declare readOnly/idempotent status, while the description adds crucial operational context: the $0.05 per-call cost via x402, the specific return data structure (per-unit rates, minimum charges, storage fees), and the payment header requirement. 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 optimally structured: purpose statement, return value specification, cost warning, then parameter details. Every sentence delivers distinct value (scope, output, cost, inputs) with no redundancy or 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 lack of output schema, the description adequately explains what data is returned (handling rates, minimums, storage fees). The paid nature of the endpoint is clearly disclosed. Minor gap: no mention of error behaviors or invalid port code handling, though openWorldHint=false implies standard validation.

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 example values for 'service' (import, export) and 'cargo_type' (general, hazardous) that the schema lacks, helping the agent construct valid filter parameters.

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

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

The description opens with a specific verb-resource pair ('Get Container Freight Station handling tariffs') and clarifies the specific domain (LCL cargo consolidation/deconsolidation at port warehouses). This distinguishes it from sibling tools like shippingrates_local_charges or shippingrates_inland_haulage by specifying the CFS/LCL 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?

The description explains the domain (CFS/LCL cargo) which implies usage context, but provides no explicit comparison to alternatives or exclusions (e.g., 'use this for LCL shipments, not FCL'). The agent must infer applicability from the domain explanation alone.

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 not found in structured fields: the payment model ('PAID endpoint: $0.02 per call via x402'), accepted currencies/networks (USDC on Base or Solana), and a preview of return values ('Congestion metrics with waiting times, delays, and trend data'). No contradictions with annotations exist.

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 follows a logical structure: purpose → use case → cost → parameters → returns. Every sentence earns its place; the payment warning is critical for a paid endpoint, and the parameter examples prevent encoding errors. No redundant or wasted language.

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 has 3 parameters (all documented), no output schema, and unique cost requirements, the description provides complete coverage: it explains what data is returned, distinguishes the tool from general port queries, and warns about the micropayment requirement—essential information for successful 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 examples for the port parameter ('INNSA', 'AEJEA'), clarifying the days_back default, and contextualizing the x_payment parameter within the broader payment workflow. This exceeds the schema's basic definitions.

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

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

The description opens with a specific verb ('Get') and clearly identifies the resource (port congestion metrics) with concrete data points (vessel waiting times, berth occupancy, delays). This distinguishes it from siblings like shippingrates_rates or shippingrates_vessel_schedule which focus on pricing and schedules rather than operational congestion metrics.

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 the tool ('assessing port efficiency and planning for potential detention costs'), giving the agent a concrete use case. However, it does not explicitly mention sibling alternatives or specific scenarios where this tool should not be used (e.g., when real-time news is needed instead of metrics).

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: cost structure ($0.02/call), payment mechanism (USDC on Base/Solana via x402), data provenance (7 trade press sources), and processing features (port tagging, severity classification). Annotations confirm read-only/idempotent safety.

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 front-loading (sources, coverage, cost). Three distinct sections (description, pricing, parameters). Minor redundancy between Args list and schema, but presents information in LLM-friendly format.

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 retrieval tool: covers payment requirements, filtering capabilities, and data scope. Missing only output format description (return structure of news items), though annotations and complete input schema partially compensate.

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 schema already documents all parameters. The Args list restates parameter purposes without adding significant semantic depth (e.g., no format examples or validation rules 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?

Specific verb 'Get' with resource 'shipping disruption news', scope '7 trade press sources', and clear geographic coverage (Hormuz, Red Sea, Suez). Distinguishes from sibling 'shippingrates_congestion' by emphasizing news content and media sources.

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: $0.02 per call' warning and payment method (x402). Implies use-case through coverage areas and news focus, though does not explicitly contrast with 'shippingrates_congestion' sibling.

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 confirm read-only/idempotent safety, the description adds essential behavioral context: the payment model (cost, currency, blockchain networks), authentication mechanism (x402 proof header), and comprehensive return structure (slab breakdown schema). It does not contradict annotations (readOnlyHint=true aligns with calculation semantics), though it omits error behavior for unpaid requests.

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 for purpose, pricing, and arguments/returns. While the Args/Returns blocks are verbose, they are justified by the absence of a formal output schema in the structured fields. The front-loading of the payment requirement ensures critical cost information is not missed.

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 (paid API, domain-specific slab calculations), the description provides comprehensive coverage including input examples and a full JSON return structure. It adequately compensates for the missing output schema. Minor gaps include lack of error handling documentation for authentication failures or invalid parameter combinations.

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 enumerating concrete examples for the 'line' parameter (maersk, msc, cma-cgm, etc.) and 'country' codes (IN, AE, SG), and clarifies that 'x_payment' is specifically for 'authenticated access' via payment proof, enhancing the schema's basic description.

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

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

The description opens with a precise action verb ('Calculate') and specific resource ('demurrage and detention (D&D) costs'), including exact scope modifiers (shipping line, country, container type, days). It distinguishes itself from siblings like 'shippingrates_dd_compare' by emphasizing the 'detailed slab breakdown' output specific to this calculation 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 identifies this as 'the core tool for logistics cost analysis' and provides critical usage constraints regarding the paid endpoint ($0.10 per call via x402) and the optional x_payment header requirement. However, it lacks explicit guidance on when to prefer this over the sibling 'shippingrates_dd_compare' or 'shippingrates_total_cost' 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 readOnly/idempotent hints, but description adds critical behavioral context not in structured data: the $0.25 payment requirement per call, the x402 payment mechanism, and that it 'Returns a side-by-side comparison' indicating the output format. 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?

Efficiently structured with purpose first, output format second, use case third, and pricing warning fourth. The Args section is well-organized. No redundant words; every sentence delivers distinct value (scope, output, use case, cost).

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 read-only comparison tool with 100% schema coverage, the description adequately covers the paid nature, return format, and parameter semantics. Could improve by explicitly contrasting with shippingrates_dd_calculate, but sufficient for correct agent invocation.

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

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

Schema has 100% description coverage (baseline 3). Description adds value by providing concrete examples for container_type ('40HC', '20DV') not present in schema, and clarifies x_payment purpose as 'x402 payment proof header' matching the schema but reinforcing the payment behavior described earlier.

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 ('Compare') and resource ('demurrage and detention costs'), explicitly scopes to 'across multiple shipping lines' which distinguishes it from sibling shippingrates_dd_calculate, and clarifies the comparison dimensions (country, container type, days).

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 ('Essential for freight procurement and carrier selection') establishing when to use, but lacks explicit 'when not to use' guidance or naming of alternatives like shippingrates_dd_calculate for single-line calculations.

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 and safe operation; the description adds critical behavioral context not covered by annotations: the $0.02 per-call cost, x402 payment requirement, and acceptable cryptocurrencies (USDC on Base or Solana), which 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 the core purpose front-loaded, followed by critical payment information. While the Args section duplicates schema content, it is cleanly formatted and the payment disclosure earns its place as vital invocation 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?

Despite lacking an output schema, the description compensates by listing return data fields (GPS, operator details, etc.) and includes essential payment context for a paid endpoint. It covers necessary invocation information, though explicit sibling differentiation would further 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?

With 100% schema description coverage, the structured schema already fully documents all 5 parameters. The Args section in the description largely repeats schema information without adding significant semantic depth or usage examples beyond what the schema 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 clearly states it searches an India ICD/CFS facility directory and specifies what data is returned (GPS coordinates, rail connectivity, operator details, capacity), using specific verbs and resource identification that distinguishes it from port or general shipping rate 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 defines the specific domain (India ICD/CFS facilities) which implies usage context for inland container logistics, but lacks explicit guidance on when to use this versus sibling tools like shippingrates_port or shippingrates_inland_search.

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 operational context beyond annotations: explicitly states 'FREE endpoint — no payment required' and documents the return object structure ({ 'rate': number, 'timestamp': string }) which is critical given the absence of an output schema. No contradictions with the readOnlyHint and idempotentHint 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, use case, cost note, args, returns). Minor redundancy between the Args section and input schema, but the Returns documentation is essential given no output schema exists. Each sentence earns its place.

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

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

For a simple 2-parameter read-only tool with complete schema coverage, the description provides comprehensive context: domain application (shipping), cost model (free), input examples, and output structure. Fully sufficient for correct agent invocation.

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

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

With 100% schema description coverage, the structured fields already define the parameters completely. The description's Args section essentially mirrors the schema (source/target currency codes with examples), adding only minor additional currency examples (INR, USD). Baseline score appropriate when schema carries the full semantic load.

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

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

The description opens with a specific verb and resource ('Get current exchange rates between two currencies'), clearly distinguishing it from shipping-specific siblings like shippingrates_rates or shippingrates_congestion. The shipping cost conversion use case further clarifies its specific role in the tool suite.

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 context for when to use ('converting shipping costs quoted in different currencies'), linking it to the shipping domain while distinguishing its currency-specific function. Lacks explicit 'when not to use' guidance, though the sibling tools' distinct purposes (congestion, schedules, tariffs) make misuse unlikely.

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 declaring read-only/idempotent safety, the description adds crucial behavioral context: return sorting (cheapest first), specific output fields (carrier, mode, weight bracket), and detailed payment mechanics (x402 protocol, USDC on Base/Solana). This adequately covers the paid nature of the endpoint.

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 information hierarchy: purpose first, return format second, payment warning third, then parameter reference. However, the Args section is redundant given complete schema coverage, and could be condensed or eliminated to reduce duplication.

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 appropriately compensates by detailing the return structure (sorted list with specific fields). It covers the payment requirement essential for a paid endpoint. Minor gap: no mention of error states (e.g., no routes found) or rate limiting.

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 appropriately met. The Args section restates parameter meanings already present in the schema without adding new semantic details (examples, validation rules, or format constraints), serving as readable documentation but not compensating beyond the structured schema.

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

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

The description clearly states the specific verb (Compare), resource (inland haulage rates), and scope (across all carriers for an ICD-port pair). It distinguishes from siblings like 'shippingrates_inland_haulage' by emphasizing comparison across carriers and 'sorted cheapest first'.

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 identifies this as a 'PAID endpoint' with specific pricing ($0.08), which is critical usage context. However, it lacks explicit guidance on when to use this versus 'shippingrates_inland_search' or 'shippingrates_inland_haulage', leaving sibling selection to implicit interpretation.

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 pricing ($0.05, x402 payment), return value structure (base rate, fuel surcharges, transit times), and payment mechanism (USDC on Base/Solana). Annotations confirm read-only/idempotent, but description adds the commercial and response format 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?

Well-structured with clear visual hierarchy: purpose statement, return value description, cost warning, and parameter list. Front-loaded with critical information (PAID endpoint prominently placed). 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 lookup tool: explains return values (base rates, surcharges, transit times) since no output schema exists, documents payment requirements, and covers all 5 parameters. Minor gap: no mention of rate limits or error conditions, but acceptable given 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% description coverage, establishing baseline 3. Description adds helpful examples (e.g., 'INNSA', 'Ahmedabad', '20GP') in the Args section, but largely mirrors schema definitions without adding significant semantic depth or parameter interdependencies.

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 verb ('Get') and resource ('inland haulage rates') with specific scope ('between ports and inland locations'). Includes transport modes (trucking/rail) in parentheses. Does not explicitly distinguish from siblings like 'shippingrates_inland_compare' or 'shippingrates_inland_search', which would elevate it to a 5.

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 context ('PAID endpoint: $0.05 per call') which constrains usage, but lacks explicit when-to-use guidance versus siblings (e.g., when to use this single-route lookup vs. 'inland_compare' or 'inland_search').

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 safety profile (readOnly/idempotent), the description adds crucial behavioral context: the cost per call ($0.03 via x402) and what the search returns ('haulage options, routes, and estimated costs'). This supplements the annotations effectively.

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, followed by behavioral details and parameter listing. Slightly redundant to repeat all parameter descriptions when schema coverage is complete, but the payment warning is appropriately 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?

Despite lacking an output schema, the description adequately explains return values ('haulage options, routes, and estimated costs') and discloses the paid nature. Complete enough for a 4-parameter search tool with clear annotations.

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

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

Schema coverage is 100%, providing complete param documentation. The description's 'Args' section largely mirrors the schema definitions without adding significant semantic depth, though it correctly marks optional params. 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?

The description clearly states the tool searches for 'inland transport routes (road/rail haulage)' and distinguishes ocean vs. inland transport. However, it fails to differentiate from sibling tools like 'shippingrates_inland_compare' or 'shippingrates_inland_haulage', which could confuse selection.

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 constraints regarding payment ('PAID endpoint: $0.03 per call'), but lacks guidance on when to use this versus related inland tools or prerequisites for the x402 payment header.

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 safety profile (readOnly, idempotent, non-destructive). Description adds valuable billing context ('FREE endpoint') and data scope transparency (specific 6 carriers included, tariff/charge record counts per country). 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, all front-loaded with critical information. Sentence 1 states purpose, 2-3 specify data content, 4 covers billing, 5 describes return type. Zero redundancy; every sentence earns its place.

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

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

No output schema exists, so description must explain return values. It specifies 'Array of shipping lines with country breakdowns' and details the included fields (number of tariff/charge records per country). Could benefit from exact field names, but adequate for a simple zero-parameter list operation.

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 zero parameters (empty properties object). Per calibration rules, 0 params = baseline 4. Description correctly implies no filtering is possible or required for this global list operation.

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 provides specific verb ('Get'), resource ('shipping lines'), and scope ('available in ShippingRates with per-country record counts'). It explicitly lists the 6 specific carriers covered (Maersk, MSC, etc.), clearly distinguishing this from siblings like shippingrates_rates or shippingrates_vessel_schedule which handle different data 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?

States 'This is a FREE endpoint — no payment required,' providing crucial context for selecting this over potentially paid alternatives among the 20+ sibling tools. Lacks explicit 'when not to use' guidance or named alternatives, but the specific scope ('per-country record counts') provides implicit filtering.

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 the operation as read-only and idempotent. The description adds crucial behavioral context not in annotations: the payment requirement (x402/USDC), cost per call, and the return value structure ('detailed breakdown'). It does not contradict annotations.

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

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

The description is well-structured and front-loaded: opening with the core purpose, followed by return value, payment warning, and parameter listing. Every sentence provides distinct information (action, output, cost, inputs) with no redundancy or 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?

Given the tool's complexity (4 parameters, paid endpoint, no output schema), the description adequately covers the essential context: payment mechanism, return description, and required vs optional parameters. It appropriately compensates for the missing output schema by describing the return value.

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 schema already documents all parameters thoroughly (including the INMUN example for port_code and the x402 explanation). The Args section in the description largely repeats the schema without adding significant semantic value or usage examples beyond the structured data.

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

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

The description clearly states the specific action ('Get local charges') and resource (port/shipping line charges), with concrete examples (THC, documentation fees, seal fees) that distinguish it from freight rates or general surcharges. The scope is precisely defined.

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 identifies this as a 'PAID endpoint' with specific pricing ($0.05), which is critical usage information. However, it lacks explicit guidance on when to use this versus siblings like 'shippingrates_surcharges' or 'shippingrates_total_cost', or when the optional port_code should be 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 read-only, idempotent safety properties, so the description appropriately focuses on adding the critical payment context ('PAID endpoint: $0.01 per call via x402') and return value structure (coordinates, timezone, facilities) not present in annotations. It does not cover error cases (e.g., invalid codes).

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 uses a clear structured format (purpose, cost warning, Args, Returns) with the most critical information (lookup purpose and cost) front-loaded. The Args/Returns sections are slightly redundant with the schema but justified by the lack of output schema and added examples.

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 comprehensively documents the return structure (port name, country, coordinates, etc.) and crucially explains the x402 payment mechanism (USDC on Base/Solana) required for invocation, providing sufficient context for a paid API 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?

While the schema has 100% coverage, the description adds valuable semantic context by mapping example codes to human-readable port names ('INNSA' → Nhava Sheva, 'AEJEA' → Jebel Ali), helping agents understand the parameter format better than the raw schema.

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

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

The description opens with a specific verb ('Look up') and resource ('port details') scoped by the unique identifier type ('UN/LOCODE'), clearly distinguishing it from sibling tools like 'shippingrates_search' or 'shippingrates_rates' which handle broader queries.

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 establishes clear context by specifying UN/LOCODE-based lookup and explicitly warns about the paid nature of the endpoint ($0.01 per call). However, it does not explicitly state when to use the general 'shippingrates_search' sibling instead for fuzzy/port-name queries.

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 safety (readOnlyHint, idempotentHint), so the description appropriately focuses on business logic. It critically discloses the payment requirement ('PAID endpoint: $0.03 per call via x402'), which is absent from annotations. It also describes the return data structure ('Array of freight rates with carrier, rate, currency...') compensating for the lack of 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?

The description is well-structured with clear sections for purpose, payment warning, arguments, and returns. It is front-loaded with the core action. Minor deduction for slight redundancy between the Args section and the input schema, though the examples justify the repetition.

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

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

For a paid endpoint with no output schema, the description is comprehensive. It discloses pricing ($0.03, USDC, networks), describes the return value structure and content (current/historical/trend), and provides examples for the non-obvious port code format. This covers all critical gaps left by the structured metadata.

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 significant value by providing concrete examples for the UN/LOCODE format ('INNSA', 'AEJEA') and container codes ('40HC', '20DV'), clarifying the expected parameter syntax beyond the schema's basic type definitions.

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

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

The description clearly states the tool 'Get[s] ocean freight rates between two ports for a specific container type,' using a specific verb and resource. It specifies the domain (ocean freight) which distinguishes it from inland haulage siblings, though it does not explicitly differentiate from closely related tools like shippingrates_total_cost 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?

The description implies usage through scope ('ocean freight rates between two ports') and mentions it returns 'current and historical rate data with trend indicators,' suggesting when to use it for trend analysis. However, it lacks explicit when-to-use/when-not-to-use guidance or naming of alternative tools from the extensive sibling list.

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, so the description appropriately focuses on additional behavioral traits: the payment model ('PAID endpoint: $0.01 per call via x402'), accepted currencies/chains (USDC on Base or Solana), and return value structure ('Array of regulatory updates with title, description...'). 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 and front-loaded: purpose first, coverage areas second, cost warning third, then Args/Returns. The Args section repeats schema info but justifies its existence with helpful examples. The Returns section compensates for the missing output schema. No wasted sentences, though the Args list is slightly redundant given perfect schema coverage.

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 3 parameters (one requiring external payment) and no output schema, the description successfully covers all critical gaps: it explains the return format, documents the cost model, and provides parameter examples. It could mention rate limits or error scenarios, but it covers the essentials 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 coverage, the baseline is 3. The description adds valuable context beyond the schema: concrete examples for country codes ('IN', 'AE', 'SG'), clarifies that x_payment is for 'x402 payment proof,' and notes the default behavior for limit. These examples and payment context enhance usability significantly.

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 ('regulatory updates and compliance requirements'), clearly scoped to 'shipping in a specific country.' It distinguishes from siblings (which focus on rates, congestion, schedules) by explicitly listing coverage areas: 'customs regulations, documentation requirements, trade restrictions, and policy changes.'

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

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

The description provides clear domain context through the 'Covers...' sentence, implying when to use this tool (for compliance/customs issues). However, it lacks explicit guidance on when NOT to use it or direct comparison to siblings like shippingrates_rates or shippingrates_search, leaving the agent to infer from the name alone.

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, while description adds critical cost behavior ('PAID endpoint: $0.02 per call via x402') and return value structure ('on-time %, average delay, sample size') not present in structured fields. No contradictions with safety 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 for purpose, use case, cost warning, arguments, and returns. Slightly redundant with schema in Args section, but earns its place by including examples and payment 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?

Complete for a paid API tool: discloses pricing mechanism (x402/USDC), describes return payload despite no output schema, and covers all 3 parameters including optional payment header. Missing only error/payment-failure behavior.

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

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

Schema has 100% description coverage (baseline 3), but description adds concrete examples beyond schema: lists enum values for line and provides 'Asia-Europe' example for trade_lane, aiding LLM inference.

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 'Get' + resource 'schedule reliability metrics' with specific data points 'on-time performance, average delays'. Distinct from siblings like shippingrates_transit_schedules or shippingrates_vessel_schedule which focus on timetables rather than performance analytics.

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 use case context ('Useful for carrier selection and benchmarking') implying when to use, but lacks explicit when-not-to-use guidance or differentiation from similar tools like shippingrates_transit that might also provide timing 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?

Strong disclosure beyond annotations: explicitly states $0.10 cost per call, payment mechanism (x402, USDC on Base/Solana), and describes the analytical scope (specific maritime chokepoints). Annotations only indicate safety (readOnly/idempotent); description adds essential commercial and domain context. Minor gap: no mention of rate limits or failure behavior.

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 hierarchy: functionality first, payment warning second, parameters third. The payment cost is front-loaded where it should be. Args section is somewhat redundant with complete schema coverage, but formatted readably. No wasted words; every sentence conveys distinct information.

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

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

Given this is a paid, complex analytical tool, the description adequately covers the unusual aspects (payment details, specific chokepoints monitored, return value range 0-100). Without output schema, it hints at return structure sufficiently. Could benefit from mentioning authentication requirements or rate limits, but covers the critical commercial constraint (paid endpoint) that annotations miss.

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 applies. The Args section repeats schema descriptions exactly (UN/LOCODE for ports, x402 header definition) without adding syntactic details, validation rules, or examples beyond what the schema already provides. The 'optional' flag for x_payment is implied by schema but explicitly stated, providing marginal value.

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 specificity: states it retrieves route risk assessment with specific data components (congestion, news alerts, chokepoint analysis) and distinguishes from siblings via unique mention of Hormuz/Suez/Bab el-Mandeb chokepoints and composite 0-100 risk score. Verb-resource combination is precise.

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 through output description (use when you need risk scores with chokepoint analysis), but lacks explicit when-to-use guidance versus siblings like shippingrates_congestion or shippingrates_reliability. No mention of prerequisites or alternatives.

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

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

Annotations already declare readOnlyHint and idempotentHint. Description adds valuable business context not in annotations: 'FREE endpoint — no payment required' and specific return value details (THC, DO_fee, BL_fee, seal_fee). No contradictions with annotation flags.

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, followed by usage guidance, billing note, and Args/Returns documentation. Minor redundancy exists in re-documenting the keyword parameter, but this is offset by additional examples and semantic clarification. 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?

Given no output schema, the description adequately enumerates return data categories (trade lanes, specific local charge types like THC/BL_fee, line info). With 22 sibling tools in a complex domain, the 'exploratory' framing provides sufficient context for selection, though explicit output structure (list vs object) is not detailed.

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 expanding valid keyword semantics beyond schema examples: explicitly mentioning 'charge type' and reinforcing that ports/countries are valid search terms alongside shipping lines, helping the agent understand the broad search surface.

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 ('Search') + resource ('ShippingRates shipping data'), and explicitly defines scope (trade lanes, local charges, shipping line info). The 'exploratory queries' framing effectively distinguishes this from sibling calculation/lookup tools like shippingrates_dd_calculate 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 guidance ('Use this for exploratory queries') with concrete examples (shipping line name, port, country). However, it lacks explicit exclusion criteria or named alternatives for when users need specific rate calculations rather than search.

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. Description adds valuable behavioral context not in annotations: cost ('FREE endpoint — no payment required') and detailed return structure (JSON example with tariff_records, last_scrape fields). 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?

Efficiently structured: purpose statement, return value enumeration, usage context, cost note, and output schema documentation. Every sentence adds value; no redundancy despite including inline return structure documentation.

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 perfectly for missing output schema by providing complete JSON return structure inline. Annotations fully cover behavioral hints. For a zero-parameter statistics tool, description provides sufficient context for correct invocation.

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

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

Input schema contains 0 parameters. Per rubric baseline, 0 params warrants a score of 4. Description correctly implies no configuration is needed for this statistics endpoint.

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' + resource 'statistics for the ShippingRates shipping intelligence database' clearly defines scope. Lists specific entities counted (tariff records, ports, trade lanes, etc.) which distinguishes this metadata tool from operational 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?

Explicitly states 'Use this to understand the scope and freshness of available data,' providing clear context for when to invoke it (pre-query validation). Notes 'FREE endpoint' for cost-sensitive decisions. Lacks explicit 'when not to use' contrast with data-retrieval 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?

Annotations declare read-only/idempotent status. Description adds crucial behavioral context not in annotations: payment requirement ('PAID endpoint: $0.02 per call'), payment mechanism ('x402'), and return structure ('Array of surcharges with type, amount, currency, effective dates').

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?

Efficient 5-section structure: purpose, return summary, payment notice, args specification, return specification. No filler text; payment disclosure is critical and earns its place. Well front-loaded with the essential action statement.

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, but description compensates by detailing return format ('Array of surcharges...'). Covers all 4 parameters including optional payment header. Given the read-only lookup nature and good annotations, coverage is sufficient though output schema would improve it.

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

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

Schema coverage is 100% with complete property descriptions. Description mirrors schema definitions in Args section without adding semantic depth (e.g., no explanation of what x402 is, no business context for direction). Baseline 3 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 ('Get') + resource ('surcharges') with parenthetical examples (BAF, CAF, PSS, EBS, etc.) + scope ('shipping line in specific country/direction'). Clearly distinguishes from sibling rate/transit tools 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?

Provides implicit usage context by listing specific surcharge categories (BAF, CAF, etc.), but lacks explicit when-to-use guidance versus siblings like 'shippingrates_rates' or 'shippingrates_local_charges'. No alternatives or exclusions 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?

Annotations establish the operation is read-only and idempotent. The description adds essential behavioral context not found in annotations: the payment requirement (financial cost per call), the aggregation logic (what 5-6 queries are being combined), and a detailed JSON structure of the return value despite no formal output schema being present.

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

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

The description is well-structured and front-loaded with the core purpose, followed by value proposition, cost warning, and documented Args/Returns sections. While the Args section duplicates schema information, it adds examples that justify its inclusion. The Returns section is valuable given the lack of formal output 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 complex tool with 6 parameters, payment requirements, and a rich return object, the description is comprehensive. It compensates for the absence of a formal output schema by providing a complete JSON structure in the Returns section, documents all parameters with examples, and discloses the financial cost model.

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

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

With 100% schema description coverage, the baseline is met. The description adds significant value by providing concrete examples for origin ('INNSA'), destination ('AEJEA', 'DELHI'), and container types ('40HC'), and clarifying the x_payment parameter's purpose as 'x402 payment proof header' beyond the schema's generic description.

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

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

The description opens with a specific verb ('Calculate') and clear resource ('full landed cost of shipping a container'), and explicitly lists the five cost components aggregated (freight, surcharges, local charges, demurrage/detention, transit time), clearly distinguishing it from sibling tools that likely handle these individually.

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 effectively positions this as an aggregation tool ('single call replaces 5-6 individual queries') and provides critical usage context via the 'PAID endpoint' warning with specific cost ($0.15) and payment mechanism (x402). It could be improved by explicitly naming sibling tools to use for individual component 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?

The annotations declare readOnlyHint=true and idempotentHint=true, confirming safe, repeatable reads. The description adds crucial behavioral context not in annotations: the payment requirement (cost, currency, blockchain), and the return format ('Array of transit options with carrier, duration, service type') which compensates 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, args, returns) and front-loaded with the essential action. While the Args list partially duplicates the schema, it earns its place by adding examples. The payment warning is prominently placed. No sentences feel wasted, though the formatting is slightly verbose.

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

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

Given the absence of an output schema, the description adequately describes the return structure. It covers the payment requirement, provides parameter examples, and explains what data is returned. It could improve by noting error conditions (e.g., invalid port codes) or rate limits, but it covers the essential behavioral and contractual context for a paid API.

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 met. The description adds value by providing concrete UN/LOCODE examples ('INNSA', 'AEJEA') that clarify the expected format, and explicitly noting that x_payment is 'optional' despite being a paid endpoint, which helps the agent understand the parameter is not strictly required in the schema sense (though payment is required for success).

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 core function ('Get estimated transit times between two ports') with specific verbs and resource. It mentions 'carrier-specific transit durations' and 'frequencies' which distinguishes it from siblings like shippingrates_transit_schedules (likely detailed timetables) and shippingrates_rates (pricing). However, it does not explicitly contrast with the similarly-named transit_schedules sibling.

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 flagging this as a 'PAID endpoint' with specific pricing ($0.02) and payment mechanism (x402 via USDC), which constrains when to invoke it. However, it lacks explicit guidance on when to use this tool versus the 20+ siblings, particularly shippingrates_transit_schedules or shippingrates_rates which may overlap in domain.

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

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

Annotations indicate read-only, safe operation, but the description adds crucial behavioral context: the per-call cost and cryptocurrency payment requirements (x402 header). It also clarifies the data scope (service codes, routing details) beyond what annotations provide.

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

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

The description is efficiently structured: purpose statement first, cost warning second, followed by organized Args list. Every sentence earns its place with no redundancy or repetition of structured schema data.

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

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

Given the lack of output schema, the description appropriately hints at return content (service codes, routing). Combined with complete parameter documentation and payment disclosure, it provides sufficient context for invocation despite missing rate limit or error handling details.

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 met. The description adds value by providing concrete examples (e.g., 'MAEU', 'maersk' for carrier) and clarifying the optional vs required nature of filters, which aids the LLM 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 clearly states the tool retrieves 'detailed transit schedules for a carrier' and lists specific data returned (service codes, routing, transhipment ports, frequency). However, it does not explicitly distinguish when to use this versus siblings like 'shippingrates_transit' or 'shippingrates_vessel_schedule'.

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 flagging this as a 'PAID endpoint' with specific cost ($0.03) and payment mechanism (x402, USDC). However, it lacks explicit guidance on when to choose this over alternative shipping tools or what prerequisites (like having x402 set up) are needed.

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

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

Annotations declare read-only/idempotent properties, so the description adds essential behavioral context not found elsewhere: explicit pricing ($0.02 per call), payment mechanism details (x402, USDC on Base/Solana), and return value structure. No contradictions with annotations detected.

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?

Efficiently structured with purpose statement first, followed by cost warning (critical for paid endpoints), then organized Args and Returns sections. No redundant words; every sentence provides distinct information not duplicated in schema or annotations.

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 given no output schema exists. The description compensates by fully documenting the return array structure and fields. Additionally covers the financial/cost implications essential for a paid API, leaving no critical gaps 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 a baseline of 3. The description adds significant value by providing concrete, valid examples for the port parameter ('INNSA', 'AEJEA') and reinforcing the payment context for x_payment that the schema only describes structurally.

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' + clear resource 'upcoming vessel schedules' + scope 'at a port', and distinguishes from siblings (e.g., shippingrates_rates, shippingrates_congestion) by focusing on vessel arrival/departure movements rather than pricing or port conditions.

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 context through the 'Returns' section explaining exactly what data structure to expect (vessel name, carrier, ETA/ETD). While it doesn't explicitly name sibling alternatives to avoid, the return specification effectively guides when to use this tool (when vessel movement details are needed). Critically warns that this is a 'PAID endpoint' with specific cost ($0.02).

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