FreightGate MCP Server

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

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses the payment requirement ($0.05/call via x402) and the 402 error response if unpaid. This provides critical behavioral context for an AI agent.

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

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

The description is concise (6 sentences) and well-structured: purpose, usage, return type, exclusion, payment info, and return fields. Every sentence adds value without redundancy.

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

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

Given no output schema, the description compensates by detailing the return array fields. It covers purpose, usage, payment, error handling, and exclusion. Minor gap: no explicit tie to sibling tools beyond FCL exclusion, but overall complete for the tool's scope.

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

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

Schema coverage is 100%, so the baseline is 3. The description mentions 'specified port' and describes the return structure, but does not add new meaning beyond what the input schema already provides for parameters.

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

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

The description clearly states the tool retrieves CFS handling tariffs for LCL cargo consolidation/deconsolidation at port warehouses. It explicitly distinguishes from FCL shipments, differentiating it from sibling tools that likely handle other shipping rates or services.

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 specifies using this tool for LCL shipments to estimate warehouse handling costs and notes it is not relevant for FCL shipments. While it does not name alternative sibling tools for FCL, the guidance on when to use is clear and prevents misuse.

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, idempotent, non-destructive behavior. The description adds critical behavioral info: the tool is paid ($0.02/call) and returns a 402 error without payment. Also lists the return fields. No contradictions.

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

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

Four purposeful sentences: purpose, usage, alternative, payment. No wasted words. Return format listed clearly.

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 low complexity (3 params, no enums, no output schema), the description covers all necessary context: what the tool does, when to use, payment requirement, and return fields. Slight improvement could include defining 'trend' more granularly, but overall complete.

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

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

Schema description coverage is 100% with clear parameter descriptions. The description adds context on the payment header parameter and the return fields, but the schema already handles most semantics well.

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 specifies the action ('Get') and resource ('port congestion metrics') with specific metrics listed. It distinguishes from the sibling tool 'shippingrates_congestion_news' by stating it is for congestion data rather than disruption news.

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

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

Explicitly states when to use ('assess port efficiency and anticipate detention risk') and when not to use (for disruption news, use the sibling tool). Provides an alternative tool name.

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 safe, idempotent read operation. Description adds behavioral details beyond annotations: payment requirement ($0.02/call, returns 402 if unpaid) and return format. 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?

Description is front-loaded with purpose, followed by usage guidance, payment info, and return structure. Concise with one paragraph; slightly dense but well-organized.

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

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

No output schema, but description compensates by detailing return array structure. Covers all key aspects: purpose, usage, parameters, payment behavior, and output format. Lacks only minor details like pagination or example.

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

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

Schema description coverage is 100%, so baseline is 3. Description does not add significant extra meaning beyond the schema; provides no examples, defaults, or dependencies. Adequate but no enhancement.

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 verb+resource: 'Get shipping disruption news aggregated from 7 trade press sources — with port tagging and severity classification.' It differentiates from siblings by specifying use for situational awareness and directing to other tools for quantitative metrics and risk scoring.

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

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

Explicitly states when to use: 'answers are there any active disruptions affecting my route?' and when not: 'For quantitative port congestion metrics... use shippingrates_congestion instead. For route-level risk scoring, use shippingrates_risk_score.' Provides clear alternatives.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description adds critical behavioral details: the pay-per-call mechanism ($0.10 via x402), the 402 error response if unpaid, and a structured sample return. No contradiction with annotations.

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

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

The description is concise (3 sentences plus return type) and front-loaded: first sentence states purpose, second gives usage guidance, third covers payment, and final line shows return structure. Every sentence adds value without redundancy.

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

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

Despite lacking an output schema, the description includes a detailed sample return structure (fields like line, country, slabs, total_cost). It also covers payment requirements and error handling, making it fully self-contained for an agent to invoke correctly.

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

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

Schema coverage is 100% with descriptions for all 5 parameters. The description does not add new param-level semantics beyond what the schema provides; it merely reiterates the container type and shipping line. Baseline of 3 is appropriate as the description adds no extra meaning.

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 begins with a clear, specific verb 'Calculate' and resource 'demurrage and detention costs' with explicit scope 'for one carrier in one country.' It distinguishes itself from the sibling tool shippingrates_dd_compare, which is clearly mentioned as an alternative for cross-carrier comparison.

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

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

The description explicitly states when to use this tool ('when the user needs a detailed cost breakdown for a specific carrier') and provides a direct alternative ('Use shippingrates_dd_compare instead'). It also frames the tool's answer in a question-answering manner, making the usage context crystal clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable context: payment cost ($0.25 via x402), behavior when unpaid (returns 402), and return format (array sorted by total_cost). No contradictions.

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

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

Description is concise, structured into three focused paragraphs: what tool does, when to use, payment info, return format. Every sentence adds value with no redundancy.

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

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

Despite no output schema, the description fully explains the return value (array with line, free_days, total_cost, currency, slabs sorted by total_cost). Combined with annotations, this gives the agent complete expectations.

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

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

Input schema has 100% coverage for 4 parameters, so schema already defines them. The description only mentions parameters implicitly (country, container type, days) without adding new semantic details. Fine but not better than baseline.

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

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

The description clearly states it compares D&D costs across ALL available carriers for given country, container type, and days. It explicitly identifies the use case (freight procurement/carrier selection) and distinguishes from sibling tool shippingrates_dd_calculate.

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 tells when to use this tool (multi-carrier comparison for cheapest D&D) and explicitly directs to shippingrates_dd_calculate for single-carrier breakdown. It also explains the payment requirement and expected response.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds critical behavioral details: it is a paid API ($0.02/call via x402) and returns 402 if unpaid. Also describes return shape (array of objects).

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?

Extremely concise: 4 sentences plus one line for return type. Front-loaded with purpose, followed by use cases and payment details. 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?

Completes the picture by specifying return structure (since no output schema) and payment requirement. Mentions combination with another tool. Could be improved by noting pagination or default behavior, but adequate for the tool's simplicity.

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

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

Input schema has 100% description coverage, so baseline is 3. Description does not add significant parameter detail beyond what the schema already provides, but it implicitly suggests using filters like state or rail_connected.

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

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

Clearly states it searches India's ICD/CFS facility directory and lists the data fields returned (GPS coordinates, rail connectivity, etc.). Distinct from sibling tools which cover rates, tariffs, etc.

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

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

States when to use: find facilities near an inland destination or check rail connectivity. Suggests combination with shippingrates_inland_haulage. Does not explicitly mention exclusions, but payment info is provided as usage context.

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

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

Annotations already mark the tool as read-only and non-destructive. The description adds valuable context: 'Rates are updated daily' and 'FREE — no payment required,' which goes beyond the annotations. It does not contradict any annotations.

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

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

The description is front-loaded with the core purpose, followed by usage context, pricing note, and return format. It is informative without being verbose, though the examples could be integrated more concisely.

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 simple tool with two parameters, full schema coverage, and no output schema, the description adequately explains behavior and return format. It covers the necessary context for an AI agent to use the tool correctly.

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

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

Schema coverage is 100% with both parameters fully described. The description provides examples like 'e.g. USD, EUR' for 'from' and 'e.g. INR, AED' for 'to', which repeats schema content. Little additional semantic value beyond what the schema offers.

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 gets the current exchange rate between two currencies, providing specific examples like USD, EUR, INR, AED. It is distinct from sibling tools which focus on shipping costs, tariffs, schedules, etc., making it easy to identify the tool's unique function.

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

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

The description explains the tool is useful for converting shipping costs quoted in different currencies to a common currency for comparison. It provides a concrete use case, but does not explicitly state when not to use it or mention alternative tools for currency conversion.

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 behavioral context beyond annotations: payment requirement ($0.08/call via x402), failure mode (returns 402 without payment), and return format. Annotations already indicate read-only and idempotent, description provides operational details.

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

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

Compact and well-structured. Front-loaded with purpose and usage. Each sentence is informative: sorting order, alternative tool, payment info, return format. No redundant phrases.

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: covers parameters, return format, payment, and usage flow. Despite no output schema, return array is described. Prerequisite tool mentioned. Adequate for complex multi-carrier comparison 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?

Schema coverage is 100%, so baseline is 3. Description adds value by providing examples for origin (e.g., INNSA) and destination, and notes default for container_type (20GP). Slight improvement over schema alone.

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

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

Clearly states verb (compare), resource (inland haulage rates), scope (across all carriers for port-to-ICD/city pair, sorted cheapest first). Distinguishes from sibling tool shippingrates_inland_haulage for single carrier 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 when to use (carrier selection on inland legs) and when not to use (for single carrier rates, use alternative). Also suggests prerequisite: use shippingrates_inland_search first to discover routes.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, indicating safe read operation. Description adds payment requirement ($0.05/call, x402) and error on non-payment (402). This exceeds annotation coverage and provides critical behavioral context.

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

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

Description is concise (~8 lines) and front-loaded with core purpose. Every sentence is informative: use case, alternatives, payment, return structure. No fluff or repetition.

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

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

For a 5-parameter tool without output schema, description explains return format (array of objects with listed fields). It covers payment, failure behavior, and common container types. Minor gap: no mention of error codes for invalid input, but overall sufficient for selection and 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% with all parameters described (origin UN/LOCODE, destination city name, container type enum etc.). Description adds value by listing return fields (carrier, rate, surcharge, total), which helps agents understand how parameters relate to output. Slightly above baseline 3 due to this added context.

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

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

The description clearly states the verb 'Get' and resource 'inland haulage rates' for moving containers between port and inland locations. It distinguishes itself from siblings shippingrates_inland_search and shippingrates_inland_compare by specifying its use case.

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

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

Explicitly states when to use: 'when you know the specific origin port and destination and need rate quotes.' Also provides alternatives: 'use shippingrates_inland_search' to discover routes and 'shippingrates_inland_compare' to compare carriers. This offers clear guidance on when-not-to-use.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds payment requirement ($0.03/call via x402, returns 402 without payment) and return format (Array of objects). No contradictions.

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

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

Each sentence is purposeful and front-loaded. The main purpose is stated first, followed by usage guidance, then payment info, then return format. No unnecessary words.

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

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

Given 4 parameters (2 required), no output schema, the description adequately covers behavior: discovery tool, returns route objects with key fields. Payment and alternative tools are mentioned, making it self-contained.

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

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

Although schema coverage is 100% (baseline 3), description adds meaning by explaining 'keyword' as 'city name, region, or route' with an example 'ahmedabad', and 'x_payment' as 'x402 payment proof header'. This adds value beyond the schema.

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

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

The description clearly states it searches for inland transport routes with specific verb 'Search' and resource 'inland transport routes (road/rail haulage) from port to inland destinations for a specific carrier'. It distinguishes from sibling tools inland_haulage and inland_compare via explicit alternative usage.

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

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

Explicitly states when to use ('discover what haulage routes a carrier offers in a country') and when not to ('For actual haulage rate quotes, use shippingrates_inland_haulage. For cross-carrier rate comparison, use shippingrates_inland_compare'). Provides a concrete example.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. Description adds value with 'FREE — no payment required' and details the return format (array with fields). No contradiction.

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

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

Very concise: three sentences plus return type line. Front-loaded with purpose, then usage, then structure. 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?

Given no parameters and no output schema, the description fully covers what the tool does, its return structure, and when to use it. Complete for its 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?

No parameters in input schema, so baseline is 4. Description doesn't need to add parameter info. It correctly omits param details as 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?

Clear verb 'List' with specific resource 'shipping lines in the ShippingRates database with per-country record counts'. Distinguishes from siblings by mentioning 'shippingrates_stats' and 'shippingrates_search' for different purposes.

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

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

Explicitly states when to use: 'Use this to discover which carriers and countries have data before querying specific tools.' Provides alternatives: 'Use shippingrates_stats for aggregate totals, shippingrates_search for keyword-based discovery.'

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds payment requirement ($0.05/call, 402 response without payment) and return format, which are not covered by annotations.

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

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

Well-structured in three paragraphs with front-loaded purpose, followed by usage guidance and payment info. Every sentence is informative and there is no fluff.

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

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

Despite no output schema, description specifies the return format (array of objects with fields). Combined with full parameter schema and annotations, the tool is fully specified 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 has 100% coverage with descriptions for all 4 parameters. Description does not add new semantic meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description precisely states the tool retrieves local charges at a port for a specific carrier, listing specific charge types (THC, documentation fees, seal fees). This clearly distinguishes it from sibling tools like shippingrates_rates or shippingrates_surcharges.

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 advises when to use ('when calculating total shipping costs at origin or destination'), and provides specific alternatives: combine with shippingrates_dd_calculate or use shippingrates_total_cost for an all-in-one estimate.

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

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

Annotations indicate readOnlyHint=true and idempotentHint=true, but the description adds critical behavioral info: the tool is PAID ($0.01/call via x402) and without payment returns a 402 status with payment instructions. This goes beyond annotations and is essential for an agent to use the tool correctly.

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

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

The description is concise (about 100 words), front-loads the purpose, and each sentence adds value: purpose, usage instructions, alternative tool, payment details, and return fields. No redundant or irrelevant text.

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 simple lookup nature and no output schema, the description provides all necessary context: what it does, how to use it (with code), alternative if code unknown, payment requirement, and a list of return fields. It is complete for an agent to correctly invoke the tool.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description provides example UN/LOCODE values but adds no new constraints or meanings beyond what's in the schema. The payment parameter is not elaborated in the description. Adequate but not exceptional.

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

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

The description clearly states the tool's purpose: lookup port details by UN/LOCODE, listing specific data fields. It also differentiates from sibling 'shippingrates_search' by specifying that this tool requires the UN/LOCODE, not a name or city.

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

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

Explicitly states when to use this tool ('validate port codes or get port metadata') and when to use an alternative ('If you don't know the UN/LOCODE, use shippingrates_search...'). Provides clear context for choosing this tool over 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 already declare readOnlyHint=true and idempotentHint=true. Description adds that it requires payment ($0.03/call) and returns 402 without payment, plus specifies return format. No contradictions.

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

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

Three compact paragraphs each serving a distinct purpose: purpose, usage guidance, and payment/return details. No wasted words.

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

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

Given no output schema, description specifies return structure (array of fields). Payment info and alternative tool are included. Annotations cover safety. Highly complete for a read-only query 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?

Schema coverage is 100%, so baseline 3 is appropriate. Description mentions optional container type filter but does not add new semantics beyond schema descriptions.

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

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

The description starts with 'Get ocean freight rates between two ports, optionally filtered by container type.' This is a specific verb+resource+scope, clearly distinguishing the tool from siblings like shippingrates_total_cost.

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

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

Explicitly states when to use (compare base freight costs) and when not (for complete cost, use total_cost). Provides clear alternatives.

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

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

Annotations indicate safe read operations. Description adds payment requirement ($0.01/call, x402), failure behavior (402 with instructions), and return structure. No contradiction.

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

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

Concise, purpose is first, then usage, then payment, then return. No unnecessary 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?

Complete for a 3-parameter tool with no output schema: covers purpose, usage, payment, return format, and behavioral notes.

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 schema fully documents parameters. Description does not add extra parameter details, meeting the baseline expectation.

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

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

Description clearly states the tool retrieves regulatory updates for a specific country, listing categories. It is distinct from siblings which cover tariffs, congestion, rates, etc.

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

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

Explicitly advises using it to stay current on regulatory changes. Does not mention when not to use or alternatives, but context makes application clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so safety is clear. The description adds valuable behavioral info: payment requirement ($0.02/call via x402) and error response for non-payment, plus a precise definition of on-time performance. No contradictions.

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

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

The description is concise (four sentences) and well-structured: function and outputs, use case and definition, payment info, return format. Every sentence is necessary and no fluff.

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

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

Given no output schema, the description explicitly lists return fields. It covers special behavior (payment), usage context, and metric definition. All necessary information is present for an agent to use the tool correctly.

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

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

Schema coverage is 100%, with all parameters described. The description does not add new parameter-level details beyond the schema, but it provides broader context about output structure and definition. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'Get' and the resource 'schedule reliability metrics for a carrier', specifying outputs like on-time performance percentage, average delay, and sample size. It distinguishes from sibling tools by focusing on reliability metrics, a unique aspect among the many shipping 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 explicitly recommends use for carrier selection and benchmarking, and defines 'on-time' with industry standard. However, it does not provide explicit when-not-to-use or alternative tools, though the context is clear.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds payment requirement and explains without payment returns 402 with instructions. No contradictions.

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

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

Concise, front-loaded with purpose, then usage guidance, payment info, return format. Each sentence adds value with no waste.

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

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

Covers purpose, usage guidance, payment, and return fields. Lacks example call or deeper calculation details, but sufficient for a tool with good schema coverage.

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

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

Schema coverage 100% with detailed descriptions. Description does not add param-specific info beyond schema but compensates by describing return structure, which is missing from output schema.

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

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

Clearly states it provides a composite risk score (0-100) for a shipping route, combining port congestion, disruption news, and chokepoint impact. Differentiates from siblings by naming specific alternatives for congestion and news.

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

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

Explicitly says when to use ('for route risk screening') and when not ('for detailed congestion metrics, use shippingrates_congestion. For news detail, use shippingrates_congestion_news'). Provides a threshold (scores above 70 indicate elevated risk).

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds valuable context: 'FREE — no payment required' and outlines the return structure (trade lanes, local charges, lines). This goes beyond the annotations, though the behavioral transparency is already well-covered.

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

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

The description is appropriately sized, with each sentence serving a purpose. It starts with the core function, then provides usage guidance, mentions cost, outlines return structure, and ends with sibling references. No redundant text.

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

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

Despite no output schema, the description outlines the return structure (trade_lanes, local_charges, lines). It also addresses cost and usage context. For a simple one-parameter search tool among many siblings, this is sufficient but could be slightly more explicit about the shape of the returned objects.

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 semantic richness: examples of valid keywords ('maersk', 'mumbai', 'hapag-lloyd'), explanation that it matches against multiple field types, and the usefulness for port codes or carrier coverage. This extra context justifies a 4.

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

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

The description clearly states the verb 'search' and the resource 'ShippingRates database by keyword', and lists the fields matched (carrier names, port names, etc.). It distinguishes from sibling tools via the 'Related tools' section, explicitly naming shippingrates_port and shippingrates_lines as 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?

The description explicitly says 'Use this for exploratory queries when you don't know exact codes' and provides examples like 'search "mumbai" to find port codes'. It also references sibling tools for structured lookups, giving clear when-to-use guidance.

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

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

Annotations already indicate read-only, idempotent, non-destructive nature. The description adds behaviorally relevant details: claims it's FREE, returns a specific object with fields like last_scrape (ISO datetime), and positions as a statistics gathering tool.

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 sentences: purpose, usage guidance, return fields. Front-loaded with purpose, no fluff. Each sentence adds value.

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

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

Given no parameters, no output schema, and good annotations, the description fully explains the tool's role, return format, and when to use it relative to siblings. Complete for a start-point statistics 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?

No parameters exist, and schema coverage is 100%. With zero parameters, baseline is 4. The description doesn't need to add parameter info, and it doesn't mislead.

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

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

The description clearly states it gets current statistics for the ShippingRates database, listing specific data categories like tariffs, charges, schedules, etc. It distinguishes from sibling tools by positioning itself as a starting point.

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

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

Explicitly says to use it as a starting point before other tools, and mentions related tools (shippingrates_lines, shippingrates_search) as alternatives for per-carrier breakdowns and keyword discovery.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. Description adds payment requirement ('PAID: $0.02/call', returns 402 without payment) and return format, which are 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?

Three well-structured paragraphs: first lists surcharges, second gives usage and alternative, third mentions payment and return format. Every sentence is valuable and 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?

No output schema, but description provides return format (array of objects with specific fields). Covers payment, alternative tool, and structure. Could mention pagination or error states, but it's fairly complete.

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

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

Schema coverage is 100% with parameter descriptions. Description does not add significant meaning beyond schema; it mentions 'carrier-specific' and 'country/direction' but these are already in schema. Baseline 3 is appropriate.

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

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

Description clearly states: 'Get carrier-specific surcharges' with examples (BAF, CAF, PSS, EBS) and specifies they are on top of base freight rates. Distinguishes from sibling tool shippingrates_total_cost.

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

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

Explicitly says 'Use this to understand surcharge exposure for a carrier in a specific country/direction' and provides alternative: 'For a complete cost breakdown, use shippingrates_total_cost which includes surcharges automatically.'

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds paid nature ($0.15/call), payment failure behavior (402), and fully specifies return structure, going 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?

Concise and well-structured: starts with purpose, then usage guidance, payment, and output format. Every sentence adds value without redundancy.

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

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

Given 6 parameters, no output schema, the description compensates by detailing the output structure, payment context, and usage boundaries. No gaps for an agent to use the tool correctly.

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

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

Input schema has 100% description coverage, so the description adds little extra meaning beyond what's already in the schema. The description mentions payment instruction but not as a parameter detail.

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

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

The description clearly states it calculates the full landed cost of shipping a container, combines multiple cost components, and explicitly distinguishes from sibling tools by noting it replaces 5-6 individual 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?

Explicitly states when to use (all-in cost estimate) and when not to (for individual components, use dedicated tools). Also mentions 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 (readOnlyHint, idempotentHint, destructiveHint) indicate a safe, read-only tool. The description adds critical context about payment requirement: 'PAID: $0.02/call via x402... Without payment, returns 402 with payment instructions.' It also describes the return format. No contradictions.

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

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

Five concise sentences, each adding value: purpose, primary use case, sibling alternative, payment info, and return format. Front-loaded with main purpose. No fluff.

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

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

Despite no output schema, the description lists fields returned (carrier, transit_days, etc.). It covers payment behavior, usage guidance, and parameter meaning. Complete for a tool with simple inputs and well-annotated schema.

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

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

Schema description coverage is 100% with clear parameter descriptions. The description does not add substantial new meaning beyond reinforcing the purpose of origin and destination. Baseline 3 is appropriate as schema does the heavy lifting.

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

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

The description clearly states 'Get estimated ocean transit times between two ports across all available carriers', providing a specific verb and resource. It distinguishes itself from the sibling shippingrates_transit_schedules by noting it is for quick comparison while the sibling handles detailed routing.

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

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

Explicitly tells when to use: 'Use this for quick transit time comparison between ports — answers "how long does it take to ship from A to B?"' and when not to: 'For detailed routing with transhipment ports and service codes, use shippingrates_transit_schedules instead.'

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

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

Annotations already indicate read-only and idempotent. Description adds payment requirement ($0.03/call via x402) and behavior if unpaid (returns 402 with instructions), plus the return structure. This provides valuable behavioral context 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?

Four sentences, each with a distinct purpose: purpose statement, usage guidance, payment info, and return format. No redundant or unnecessary content.

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 5 parameters, 100% schema coverage, and no output schema, the description provides the return structure, usage context, payment details, and clear purpose. It covers all necessary aspects for an agent to decide and 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 parameter descriptions already present. The description repeats that origin and destination are UN/LOCODE filters and carrier is SCAC code/slug, but adds no new semantic details beyond the schema.

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

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

Description clearly states the tool returns detailed transit schedules including service codes, transhipment ports, transit days, and frequency. It uses specific verb 'Get' and distinctively lists the detailed fields, differentiating from the sibling tool shippingrates_transit for quick transit time comparison.

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

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

Explicitly states when to use this tool ('when you need routing details beyond just transit time') and when not to ('for a quick transit time comparison across all carriers, use shippingrates_transit instead'), providing a clear alternative.

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

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

Discloses payment requirement ($0.02/call, unpaid returns 402 with instructions) and return structure (array of objects with fields), adding value beyond annotations which already indicate read-only and idempotent.

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

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

Concise, front-loaded with main purpose, then usage, alternatives, payment, return format. No redundant sentences; all information earned 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?

Given no output schema, description provides return structure. Covers purpose, usage, payment, error handling, and parameter context. Complete for a 3-parameter tool with complex domain.

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 descriptions for all parameters. Description adds port code examples (INNSA, AEJEA, SGSIN) and reinforces default for days_ahead, providing helpful context beyond schema.

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

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

Clearly states it gets vessel arrivals/departures at a port. Distinguishes from siblings by explicitly naming shippingrates_transit and shippingrates_transit_schedules for alternative use cases.

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

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

Explicitly says when to use (booking planning/tracking) and when not to (transit time estimates → use shippingrates_transit; detailed routing → use shippingrates_transit_schedules).

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

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

Discloses that missing cutoff fields remain null, that it does not infer unpublished deadlines, and the payment behavior (returns 402 without payment). Annotations already indicate read-only, non-destructive, idempotent, but description adds operational constraints.

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 front-loaded with purpose, followed by usage guidance, payment info, and return structure. Every sentence adds value with 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?

Given complexity (6 params, no output schema, many siblings), the description provides comprehensive context: purpose, when to use, payment, alternative tool, and return format. Annotations further support.

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 good descriptions for all 6 parameters. The description adds minimal extra semantics beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states it gets carrier vessel/voyage schedule options between an origin and destination, including cutoff deadlines. It distinguishes from sibling shippingrates_vessel_schedule by specifying the inclusion of cutoffs.

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 tells when to use (booking planning needing vessel details and cutoffs) and when not (port-call monitoring without cutoffs, pointing to sibling). Also mentions payment requirement and cost.

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