FreightGate MCP Server

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds crucial behavioral context: payment requirement ($0.05/call via x402), failure behavior (returns 402 with payment instructions when unpaid), and output format. These details go beyond the annotations and are essential for the agent to invoke 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 and well-structured: it opens with the core purpose, follows with usage context, then payment instructions, and ends with return format. Every sentence earns its place with no filler or redundancy, making it easy to parse quickly.

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

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

The tool has no output schema, so the description compensates by listing the exact return array fields. It also covers purpose, usage, payment, and exclusions. It doesn't explain filter parameter values (service, cargo_type) in detail, but those are self-explanatory from the schema. Overall, it provides sufficient context for a tool of this complexity.

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

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

Schema coverage is 100%—all four parameters have descriptions in the input schema. The tool description does not add additional parameter semantics beyond what the schema already provides, but it does mention 'the specified port' and return fields. This meets the baseline of 3 for high schema coverage, but no extra value is added.

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

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

The description clearly states the tool's purpose: 'Get Container Freight Station (CFS) handling tariffs' with specific detail on LCL cargo consolidation and deconsolidation. It distinguishes from sibling tools by focusing on a specific niche (CFS tariffs) and explicitly excludes FCL shipments, making it unique among the shippingrates_* family.

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

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

Provides explicit guidance: 'Use this for LCL shipments to estimate warehouse handling costs' and 'Not relevant for FCL (Full Container Load) shipments.' This gives clear when-to-use and when-not-to-use context, satisfying the guideline requirement even without naming an alternative tool.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses important behavior: null fields for unavailable measurements, 'unknown' severity, the specific denominator (USLAX), and the payment requirement that returns a 402 without payment. It also describes the return envelope, adding significant context.

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

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

The description is well-structured and front-loaded with the purpose. It is moderately sized but every sentence contributes: purpose, behavior, alternative, payment, and output format. No redundant filler.

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

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

Given no output schema, the description compensates by outlining the return envelope ('{ port, port_name, current_level, days_back, history[] }') and explaining null/unknown semantics. It also names the sibling alternative and payment behavior. A minor gap is not explaining the meaning of 'current_level' or 'history', but overall it is complete enough 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%, and the schema already includes descriptive text for all parameters (port, days_back, x_payment). The description adds minimal extra semantic value, mainly reiterating the USLAX denominator and payment instruction, which are already in the schema. Baseline 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'Get certified port-authority congestion measurements for a specific port.' It explicitly distinguishes from the sibling tool shippingrates_congestion_news, which is for disruption advisories, making the purpose unmistakable.

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

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

It provides clear when-to-use guidance: use this for certified congestion measurements, and explicitly states an alternative for disruption advisories ('use shippingrates_congestion_news instead'). It also notes the paid requirement and the 402 failure mode, which are practical usage constraints.

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

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

The description goes well beyond the annotations (readOnly, idempotent, non-destructive) by explaining filtering logic ('only explicit operational-disruption terms enter the customer result'), the empty-result behavior ('stays empty instead of inventing an alert'), and the payment mechanism. These behavioral details are not evident from annotations alone and significantly aid the agent in anticipating tool 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?

The description is front-loaded with the core purpose, followed by scope details, alternatives, payment info, and return format. Every sentence serves a distinct purpose with no redundancy, and the entire description fits in a compact, scannable structure.

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

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

Despite no output schema, the description lists the exact returned fields ({ headline, summary, source, port_code, severity, published_at }). It also covers source scope, filtering behavior, payment quirks, and sibling differentiation. For a read-only news-query tool of this complexity, nothing essential is missing.

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

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

Input schema coverage is 100%, so all parameters already have clear descriptions. The tool description does not add meaningful parameter semantics beyond what the schema provides; it only references payment in a general sense. Baseline 3 is appropriate because the schema carries the descriptive weight.

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

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

The description opens with a specific verb+resource: 'Get certified shipping-disruption publications from reviewed official port-authority sources.' It clearly distinguishes itself from siblings by naming shippingrates_congestion (quantitative) and shippingrates_risk_score (route-level risk) as alternatives, making the tool's unique purpose unmistakable.

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

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

Explicit guidance is provided: 'For quantitative measurements, use shippingrates_congestion. For route-level risk scoring, use shippingrates_risk_score.' This tells the agent exactly when to choose this tool over its siblings. Payment prerequisites and the 402 response without payment are also disclosed, giving clear usage context.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), the description adds significant behavioral context: it details return contents (free days, per-diem rates, total cost), explains the storage charge variant and its thin coverage, promises explicit 'no data' errors instead of false $0, and discloses the 402 payment requirement with x402. 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 detailed yet tightly structured: front-loaded purpose, then usage context, alternative, storage notes, payment info, and return shape. Every sentence contributes new information without redundancy or fluff. It is appropriately sized for the tool's complexity.

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

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

Given the tool's complexity (7 params, 4 enums, payment requirement, no output schema), the description is remarkably complete: it names all return fields, explains the storage exception with coverage caveats, covers error behavior, and provides the access cost. The return schema is absent, so the explicit return list compensates fully.

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 description coverage is 100%, the description adds meaningful parameter-level insight not captured in the schema: charge_type='storage' is a distinct terminal charge never mixed into default D&D, the coverage for storage is thin, and error handling is explicit. It also clarifies the x_payment parameter's role in paid access, going beyond the schema's simple field label.

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

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

The description opens with a clear, specific statement: 'Calculate demurrage and detention (D&D) costs for one carrier in one country.' It also distinguishes the tool from its sibling by explicitly naming shippingrates_dd_compare for all-carrier comparisons, satisfying the requirement for verb+resource+scope and sibling differentiation.

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

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

The description provides explicit when-to-use guidance ('Use this when the user needs a detailed cost breakdown for a specific carrier') and names the alternative tool for cross-carrier comparisons ('To compare D&D costs across all carriers at once, use shippingrates_dd_compare instead'). It also clarifies when to use charge_type='storage' rather than default D&D, and even notes coverage limitations.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses payment behavior ('PAID: $0.25/call via x402'), error response for non-payment ('Without payment, returns 402'), and output sorting ('sorted by total_cost ascending'). This adds meaningful behavioral context not present in annotations.

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

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

The description is well-structured and front-loaded: purpose, usage, alternative, payment, and return format. Each sentence adds distinct value with no filler. It is longer than average but 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?

Given the lack of an output schema, the description fully covers the return shape ('Array of { line, free_days, total_cost, currency, slabs }'), sorting, and pricing behavior. It also covers when to use the tool and the alternative, making it complete for agent decision-making.

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 parameters are already well-documented. The description restates the parameters ('country, container type, and detention days') but adds no additional semantic detail beyond what the schema provides. 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 opens with a specific verb+resource: 'Compare demurrage and detention costs across ALL available carriers' with clear scope ('same country, container type, and detention days'). It also distinguishes itself from sibling tool by explicitly mentioning shippingrates_dd_calculate for single-carrier breakdowns.

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

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

Explicit usage guidance is provided: 'Use this for freight procurement and carrier selection' and it answers a concrete question. It also gives an explicit alternative: 'For a single carrier's detailed D&D breakdown, use shippingrates_dd_calculate 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?

Beyond annotations (readOnly, idempotent, non-destructive), the description discloses that arrival_date is user-supplied (data_basis = user_supplied_arrival), that the clock starts at a carrier-defined event, that storage coverage is thin and returns explicit 'no data' errors with covered lanes, that payment is required ($0.10/call) and non-payment returns 402, and that the response includes a charge_family field for disambiguation. 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 about 180 words but every sentence earns its place. It is front-loaded with the core function, then use case, then behavioral details, then payment, then return fields. No filler or redundant phrasing.

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 8 parameters, 4 enums, no output schema, and complex business logic, the description is remarkably complete. It covers the use case, free-time clock semantics, data basis, charge-type override, payment requirements, error behavior, and return field names. An agent has enough to invoke it correctly.

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

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

Schema covers 100% of parameters with descriptions, so baseline is 3. The description adds meaning for key parameters: arrival_date defines the free-time clock and is user-supplied, charge_type='storage' switches to a distinct terminal charge with thin coverage, and x_payment is the payment proof header for paid access. This is extra context beyond the schema, warranting 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 states exactly what the tool does: given a container's carrier, country, type, and arrival date, it reports free days remaining, first chargeable day, per-diem, accrued cost, and forecast. It also distinguishes from the sibling tool shippingrates_dd_calculate by framing itself as 'the proactive companion' that answers a different question.

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 it: to answer 'how long until this container starts costing demurrage, and how much per day?' It contrasts with shippingrates_dd_calculate, which answers a fixed number of days. It also gives guidance for using charge_type='storage' and warns about thin coverage, including the explicit 'no data' error case.

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

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

Beyond the annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false), the description discloses critical behavioral traits: a $0.02/call payment via x402, a 402 response without payment, and that optional operational attributes remain null unless certified. It also clarifies the current edition does not assert GPS, rail, operator, or capacity data. This adds substantial context for an agent selecting the 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?

The description is reasonably concise at four sentences, covering purpose, usage, payment, and return shape. Each sentence provides necessary information, though the phrase 'source-published facility code, name, and type' could be tightened to match the actual schema parameters.

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

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

The description covers purpose, payment, limitations, and return shape, which is good for a search tool. However, it does not explain how multiple filters combine (e.g., AND vs OR), nor does it resolve the discrepancy between the claimed 'name' search and the schema. Since there is no output schema, the vague 'existing facility response shape' is acceptable but could be more explicit.

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

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

The input schema has 100% description coverage, so the baseline is 3. The description adds a useful caveat about rail_connected data not being asserted, which helps interpret that filter. However, it claims search by 'name' while the schema defines no name parameter, creating confusion. It does not add meaningful semantic detail for the 'code', 'state', or 'x_payment' parameters beyond the 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 clearly states the tool's function: 'Search India's current official ICEGATE Inland Container Depot (ICD) and Container Freight Station (CFS) directory by source-published facility code, name, and type.' It distinguishes itself from siblings by focusing on the official ICEGATE facility directory. However, the mention of searching by 'name' is misleading because the input schema has no 'name' parameter, only 'code', 'type', 'state', and 'rail_connected'.

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

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

The description provides explicit usage guidance: 'Use this to resolve an official ICEGATE ICD/CFS code or facility name.' It also indicates what the tool does not provide (GPS, rail, operator, capacity data) and notes that unsupported attributes remain null. It lacks an explicit comparison to sibling tools like shippingrates_inland_search, and the 'facility name' part is unsupported by the schema, which slightly undermines the guidance.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive hints. The description adds substantive behavioral context beyond these: the rate is 'certified ECB reference rate' updated on ECB working days, unsupported currencies fail closed, and it is FREE. The return field list also clarifies output behavior. No contradiction with annotations.

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

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

The description is well-structured and front-loaded: it starts with the core action, then use case, then operational details, then free status, then return format. Every sentence adds distinct value without redundancy. It is appropriately sized for the tool's simplicity.

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 low complexity (two parameters, no nested objects, no output schema), the description is complete. It covers use case, update cadence, failure behavior, cost, and the exact return shape. Annotations provide the safety profile, so no gaps remain.

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

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

Schema coverage is 100% with clear descriptions and examples for 'from' and 'to'. The description adds extra meaning by clarifying that the tool works 'between two supported currencies' and that 'unsupported currencies fail closed', which indicates handling of invalid parameter values. This goes beyond the schema but doesn't fully explore parameter nuances, so a 4 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 a specific verb+resource: 'Get the current certified ECB reference rate between two supported currencies.' It explicitly distinguishes itself from sibling tools by focusing on currency exchange, a unique function among shippingrates_* tools. The mention of 'convert shipping costs' provides concrete purpose.

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

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

The description gives explicit context: 'Use this to normalize costs from different carriers/countries to a common currency for comparison.' It also notes that unsupported currencies fail closed. However, it does not provide explicit when-not-to-use guidance or name alternative tools, so it falls short of a 5.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: payment is required ($0.08/call via x402, returns 402 without payment), ramp and door rates are never mixed, and results are sorted ascending by rate. 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 four sentences, each serving a distinct purpose: core function, usage context/alternatives, delivery_mode caveat, payment note, and return shape. It is front-loaded with the most important information and has no filler.

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

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

With no output schema, the description compensates by specifying the exact return format: an array of objects with named fields sorted by rate ascending. It also covers payment failure behavior (402), delivery_mode behavior, and defaults. This is fully adequate for selecting and invoking 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 description coverage is 100%, so baseline is 3. The description does not introduce new parameter-level details beyond what the schema already provides; it repeats the delivery_mode default and 'never mixed' rule already in the schema. However, it contextualizes x_payment with the payment requirement, giving slight additional 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 opens with a specific verb and resource: 'Compare inland haulage rates across ALL available carriers for a port-to-ICD/city pair — sorted cheapest first.' It clearly states the scope (all carriers, specific route) and distinguishes itself from sibling tools by explicitly naming 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?

Provides explicit when-to-use guidance: 'Use this for carrier selection on inland legs.' It names alternatives: 'For a single carrier's rates, use shippingrates_inland_haulage instead. To discover what routes exist, use shippingrates_inland_search first.' Also clarifies shippingrates_cfs_tariffs and shippingrates_dd_compare are not relevant.

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, but the description adds valuable behavioral context: the tool is paid ($0.05/call via x402), without payment returns 402 with payment instructions, and specifies the full return field list. This goes beyond the annotations' safety profile and provides actionable operational details.

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

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

The description is well-structured and front-loaded with purpose, followed by usage context, sibling guidance, payment details, and return format. Every sentence adds necessary information without redundancy or filler. It is appropriately concise for the tool's complexity.

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

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

Despite having no output schema, the description lists the exact return array structure ({ carrier, origin, destination, container_type, rate, fuel_surcharge, total, currency, transit_days, mode, delivery_mode, icd_code }). It also includes payment requirements, error behavior (402), and clear usage context. For a read-only rate lookup with 8 parameters, this is complete.

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

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

Schema description coverage is 100%, so the parameters are already well-documented (e.g., origin UN/LOCODE, destination city, mode, container_type). The description does not add extra parameter semantics beyond what the schema provides, but it does mention return fields like 'base rate, fuel surcharges' which is not parameter-specific. This aligns with the baseline 3 for high schema coverage.

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

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

The description clearly states the tool provides inland haulage rates (trucking/rail) for port-to-inland moves, using a specific verb ('Get') and resource. It distinguishes itself from siblings like shippingrates_inland_search (route discovery) and shippingrates_inland_compare (carrier comparison) by explicitly naming them 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 states when to use: 'Use this when you know the specific origin port and destination and need rate quotes.' It also provides clear guidance on alternatives: 'To discover what routes exist first, use shippingrates_inland_search. To compare rates across all carriers for the same route, use shippingrates_inland_compare.' This fully satisfies the dimension.

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 non-destructive. The description adds valuable behavioral context: the $0.03/call payment requirement, 402 error without payment, and the return structure. No contradiction with annotations.

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

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

The description is front-loaded with purpose, followed by usage example, alternatives, payment info, and return shape. Each sentence earns its place with no fluff, and the length is justified by the useful 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 no output schema, the description explicitly specifies the return array structure, covering the missing output documentation. Combined with payment details, usage examples, and alternative tool references, it is fully complete for a search 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?

Schema description coverage is 100%, so the baseline is 3. The description reinforces required params (line, country) and provides an example keyword, but does not add significant detail beyond the schema's property 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 clearly states the tool searches for inland transport routes for a specific carrier, using a specific verb and resource. It explicitly distinguishes from sibling tools by naming shippingrates_inland_haulage and shippingrates_inland_compare 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?

Provides explicit when-to-use guidance: 'Use this to discover what haulage routes a carrier offers in a country' with a concrete example. Clearly names alternatives for rate quotes and comparison, satisfying the when-not/alternatives criterion.

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. The description adds meaningful context beyond that: the 'reviewed' and 'live D&D coverage' filters, the return format ('Array of { shipping_line, country, records }'), and the note that it's FREE. These details enrich the behavioral profile without contradicting the annotations.

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

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

The description is five short sentences, each earning its place: purpose, usage, free status, return shape, and related tools. It is front-loaded with the core action and scoping, 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?

For a zero-parameter list tool with no output schema, the description fully compensates by stating the exact return structure and the data filter. It also gives usage context and sibling guidance, making it self-sufficient for an agent to decide when and how to invoke 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?

The tool has zero parameters, so the baseline is 4. The description doesn't need to explain parameters, and it correctly implies the tool lists all matching lines without requiring input. The schema coverage is 100% (vacuously), and the description adds no misleading parameter info.

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: 'List reviewed shipping-line identities that currently have live D&D coverage, with per-country record counts.' It clearly distinguishes this tool from siblings by focusing on reviewed live coverage and per-country counts. The 'Related tools' line further differentiates from shippingrates_stats and shippingrates_search.

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

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

It explicitly states when to use the tool: 'Use this to discover which carrier-country D&D combinations are currently available before querying a tariff tool.' It also provides alternatives: 'Use shippingrates_stats for aggregate totals, shippingrates_search for keyword-based discovery.' This fully answers 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?

The description adds value beyond annotations by disclosing that it is a paid endpoint, returns HTTP 402 without payment, and specifies the return structure (array of objects with charge details). Annotations already indicate readOnly and non-destructive behavior, so this extra context is beneficial and does not contradict.

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

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

The description is concise and well-structured: it starts with a succinct definition, follows with usage guidance, then payment terms, and finally a clear return format. Every sentence adds value without redundancy or filler.

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

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

For a tool with four parameters, two required, and no output schema, the description covers the essential context: what it returns, when to use it, how it relates to other tools, and the payment/error behavior. The provided return format compensates for the lack of an output schema, making the description fully sufficient.

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

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

Schema coverage is 100%, with all parameters already described in the input schema. The description adds minimal extra meaning beyond the schema, such as clarifying that port_code is a filter and x_payment is a payment proof header, but most parameter semantics are already conveyed. No parameter details are omitted or misinterpreted.

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 identifies the tool as retrieving local port charges (THC, documentation fees, seal fees, etc.) for a specific carrier, with a distinct verb and resource. It distinguishes itself from sibling tools by explicitly naming alternatives like shippingrates_dd_calculate and shippingrates_total_cost, clarifying its scope.

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

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

Usage guidance is explicit: 'Use this when calculating total shipping costs at origin or destination.' It also gives alternatives ('Combine with shippingrates_dd_calculate... or use shippingrates_total_cost...') and notes the payment requirement (PAID: $0.05/call) as a condition of use.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds critical behavioral context beyond annotations: the x402 payment requirement ($0.01/call), the 402 error response when payment is missing, and the exact return structure. This gives the agent a full picture of cost and failure modes.

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

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

The description is four sentences, each serving a distinct purpose: core functionality, usage guidance, payment note, and return format. It is front-loaded with the essential verb and resource, contains no redundant phrases, and 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?

For a simple lookup with one required parameter and no output schema, the description covers all necessary context: the input (UN/LOCODE), the alternative when input is unknown, the payment requirement, and the return fields. There are no open gaps for an agent to safely invoke this 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%, including descriptions for both parameters. The description mentions using UN/LOCODE and the return fields, but adds no extra semantic detail beyond what the schema already provides. Baseline 3 is appropriate since the 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 a specific action and resource: 'Look up port details by UN/LOCODE' with explicit fields (name, country, coordinates, timezone, facilities). It also distinguishes from the sibling 'shippingrates_search' by defining when this tool is appropriate (when the UN/LOCODE is known).

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

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

Provides explicit when-to-use guidance: 'Use this to validate port codes or get port metadata.' It also gives an alternative: 'If you don't know the UN/LOCODE, use shippingrates_search with the port or city name first.' Payment requirements are also stated, clarifying a prerequisite for invocation.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds critical behavioral context: the $0.03 payment requirement via x402, the 402 response without payment, and the empty rates array for unsupported lanes. This goes beyond the structured hints.

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

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

The description is front-loaded with the core purpose, then provides essential context about data source, payment, and return format in a compact structure. Every sentence serves a 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?

Given the tool has no output schema, the description fully specifies the return structure inline, including nested rate fields and optional top-level fields. It also covers payment behavior and edge cases (unsupported lane), making it self-contained 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 covers 100% of parameters with descriptions, so baseline is 3. The description adds value by explaining the x_payment parameter's role in the payment mechanism and reiterating that container_type is an optional filter. It doesn't add much syntax beyond schema, but the payment context is meaningful.

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

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

The description opens with "Get current certified freight benchmark observations between two ports, optionally filtered by container type" – a specific verb, resource, and scope. It further distinguishes from siblings by noting these are "official published market indices, not carrier spot quotes or contracted rates" and names an alternative 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?

Explicitly clarifies when to use this tool (for official published indices) and when not (it is not for spot quotes or contracted rates). It also directs users to 'shippingrates_total_cost' for multi-component estimates, making the alternative explicit.

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

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

Despite annotations already declaring readOnlyHint, idempotentHint, and destructiveHint, the description adds crucial behavioral context: it is a PAID tool ($0.01/call via x402) and without payment returns HTTP 402 with payment instructions. This is significant beyond annotations and aids the agent in anticipating failures. It also discloses the return structure.

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

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

The description is concise and well-structured, with a clear lead sentence, a usage line, payment note, and return format. Each sentence adds distinct value and no filler is present.

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

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

Given that there is no output schema, the description compensates by fully specifying the return structure (array of updates with field list). It also explains the payment mechanism and error condition (402), making the tool behaviorally complete for an agent.

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

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

Schema coverage is 100%, with each parameter (country, limit, x_payment) having a description. The description adds no further parameter-level detail beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly states the verb ('Get') and resource ('recent shipping regulatory updates and compliance requirements for a specific country'), listing specific categories (customs regulations, documentation requirements, trade restrictions, policy changes). This is specific and distinct from sibling tools like tariffs or congestion.

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

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

It provides a direct usage instruction ('Use this to stay current on regulatory changes that may affect shipments to/from a country'), giving a clear context for when to use it. However, it does not explicitly mention alternatives or when not to use it, so it stops short of full when/when-not guidance.

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

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

Beyond the readOnly/idempotent annotations, the description adds meaningful behavioral details: only published metrics are returned (others null), payment is required via x402 with a 402 on failure, and the envelope shape (source, period, freshness, published metrics). This is substantial added context, though it could be even richer (e.g., rate limits).

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

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

The description is four sentences, each with a distinct purpose: what the tool does, when to use it, payment behavior, and return envelope. It is front-loaded and concise, though slightly longer than strictly necessary.

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

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

For a simple read-only tool with three parameters and no output schema, the description covers the essential context: purpose, use case, payment requirement, and return envelope. It doesn't list specific metric field names but that's acceptable given the high-level nature of 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?

The input schema covers all parameters (100% coverage), describing line, x_payment, and trade_lane clearly. The description does not add extra semantic meaning 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 opens with a specific verb and resource: 'Get the latest certified public schedule-reliability highlights for a carrier.' This clearly distinguishes it from sibling tools like shippingrates_congestion or shippingrates_transit by focusing on schedule reliability highlights.

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

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

Provides explicit use context ('Use this for carrier selection and high-level benchmarking'), which helps the agent decide when to invoke this tool. However, it does not mention exclusions or alternative tools, missing the full 'when-not/alternatives' rubric for a 5.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses deterministic behavior, the scoring rule (unknown inputs zero, only when a signal applies), the immutable UN/LOCODE mapping, payment requirements, the 402 error case, and the exact return shape. This is very rich behavioral context with no contradiction to 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 dense but every sentence earns its place: purpose, scoring rules, alternatives, payment, and return shape are all included without fluff. It is front-loaded with the most important information and stays focused.

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

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

Given there is no output schema, the description compensates by explicitly stating the API result shape. It also covers payment/error behavior and scoring edge cases, making the tool fully understandable to an agent. The combination of annotations and description leaves no critical gap.

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

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

The schema already provides full descriptions for origin, destination, and x_payment, so the baseline is 3. The description adds valuable context above that: the payment amount ($0.10 via x402), network details (USDC on Base or Solana), and the certified chokepoint mapping relevance. It does not need to restate parameter formats since the schema covers them.

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

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

The description opens with a specific verb and resource: 'Get a deterministic route-risk score (0-100)'. It clearly defines what the tool calculates and its inputs (port congestion measurements, disruption advisories), and distinguishes it from the sibling tools by naming shippingrates_congestion and shippingrates_congestion_news for other 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?

The description explicitly states when this tool should be used and when not: 'unsupported routes return no result instead of an estimated score'. It also gives direct alternatives: 'For exact measurements, use shippingrates_congestion. For advisory detail, use shippingrates_congestion_news.' This is strong, actionable guidance.

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

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

Annotations already declare the tool as read-only, open-world, and idempotent. The description adds valuable behavioral context about data coverage ('Uncertified families remain empty and legacy rows are never used as a fallback') and the free availability, which goes beyond the annotations. 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 compact and front-loaded with the core purpose. Each sentence serves a distinct function: scope definition, data behavior note, free status, return format, and related-tool guidance. No unnecessary repetition or filler.

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

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

Given the tool has only one parameter and no output schema, the description adequately covers the return structure (query and results categories) and notes important data limitations. It does not mention details like pagination or result ordering, but for a simple keyword search with strong annotations and schema coverage, the description is sufficiently complete.

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

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

The schema fully documents the keyword parameter with examples, providing baseline coverage. The description enriches the parameter meaning by explaining what the keyword searches across (port codes/names, carrier identities, transit services, local-charge names/carriers), which helps the agent understand the search scope beyond 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 clearly states the tool searches customer-published ShippingRates datasets by keyword and enumerates the specific data categories it matches (certified port codes/names, reviewed carrier identities, published transit services, local-charge names/carriers). It also distinguishes itself from sibling tools by explicitly referencing shippingrates_port and shippingrates_lines 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?

The description provides explicit usage guidance by naming related tools and their purposes: 'Use shippingrates_port for structured port lookup by UN/LOCODE, shippingrates_lines for full carrier listing.' This clearly indicates when this search tool is appropriate versus its alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond these: counts include only 'certified dependencies that are currently publishable,' uncertified families report zero instead of falling back to legacy rows, and it is 'FREE — no payment required.' It also specifies the return structure (fields with last_scrape as ISO datetime). No contradictions with annotations. This is rich behavioral disclosure.

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

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

The description is well-structured with clear sections: purpose, usage, caveat, free status, return format, and related tools. Every sentence earns its place; there is no fluff. It is appropriately sized for a zero-parameter tool with no output schema, front-loading the core purpose and usage.

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 zero parameters and no output schema, the description is fully complete. It explains what the tool returns (all field names), when to use it, the caveat about certified dependencies, and the free status. For a simple stats tool, this is sufficient context for an agent to invoke it correctly without requiring additional information.

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

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

The tool has zero parameters, so the baseline for this dimension is 4. The description does not need to explain parameters but compensates by clearly describing the return fields (tariff_records, ports, etc.), giving semantic meaning to what the tool outputs. This adds value beyond the empty schema.

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

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

The description clearly states the tool's function: 'Get current counts from ShippingRates customer-published datasets.' It uses a specific verb ('Get'), names the resource ('current counts'), and distinguishes itself from sibling tools by noting it provides aggregate statistics ('counts') rather than per-carrier or search results. It also explicitly mentions related tools for alternative uses.

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

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

The description provides explicit usage guidance: 'Use this before calling data tools.' It also lists related tools and what they are for ('shippingrates_lines for per-carrier breakdowns, shippingrates_search for keyword discovery'), which helps the agent decide when to use this tool versus alternatives. This goes beyond mere context and gives actionable direction.

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

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

Annotations already declare read-only and idempotent behavior. The description adds important behavioral context: the $0.02/call payment requirement via x402 and the 402 response without payment. It also describes the return array structure, which is useful since no output schema exists.

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

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

The description is well-structured with short, purposeful paragraphs. It front-loads the main purpose, then covers usage, payment, and return format without redundancy. Every sentence adds value, achieving high informational density.

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 compensates by explicitly listing the return fields. It also covers the payment prerequisite, alternative tool, and domain context (surcharges on top of base rates). The tool is a read-only lookup with simple parameters, and the description is sufficiently complete.

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

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

The input schema already provides descriptions for all 4 parameters (100% coverage), so the baseline is 3. The description adds context about surcharges being added to base freight rates and mentions country/direction, but does not provide additional syntax or format 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?

The description clearly states the tool's function: 'Get carrier-specific surcharges' and lists specific surcharge types (BAF, CAF, PSS, EBS), establishing a distinct purpose. It also differentiates from shippingrates_total_cost, making the tool's scope unambiguous.

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

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

The description says when to use the tool ('to understand surcharge exposure for a carrier in a specific country/direction') and explicitly directs users to shippingrates_total_cost for a complete cost breakdown, providing a clear alternative and exclusion.

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

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

Beyond the annotations (readOnlyHint, idempotentHint), the description discloses critical behavior: the result can be partial, missing components are zero only when explicitly reported, payment is required (402 without payment), and the headline total sums only mandatory charges with additional costs itemized separately. This goes well beyond annotations and is essential for correct use.

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 long but well-structured, with purpose, caveats, payment, return format, and a critical note. Each section earns its place given the complexity of the tool. It is not as concise as the calibration example but avoids redundancy and fluff.

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

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

With no output schema, the description provides a detailed return structure including components, coverage, data_gaps, transit_days, and multiple total cost fields. It also covers payment requirements, partial results, and the distinction between mandatory and additional charges, making it complete for a complex 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 baseline is 3. The description adds interpretive value by connecting parameters to the estimate (e.g., 'requested demurrage/detention exposure' maps to detention_days, FX and transit context are mentioned) and clarifies how missing components are handled, which indirectly affects parameter interpretation.

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

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

The description clearly states a specific verb ('Calculate') and resource ('published multi-component shipping-cost estimate') with scope. It distinguishes this tool from siblings by explicitly naming alternative tools for individual components (e.g., shippingrates_rates, 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?

The description provides explicit usage guidance by cautioning that 'A market index is not a carrier quote' and instructing to 'Always inspect coverage, data_gaps, total_is_partial, warning' before quoting. It also names alternative tools for individual components, making when-to-use vs. when-not-to-use 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, and destructiveHint=false, so safety profile is covered. The description adds important context: the paid nature ($0.02/call via x402), the 402 response without payment, and the return structure. This goes beyond annotations to disclose auth/payment behavior and output shape.

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

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

The description is compact and front-loaded: the first sentence states the core action, followed by usage, alternative, payment, and return format. Every sentence earns its place, with no redundant filler.

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

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

Despite having no output schema, the description explicitly lists the return array structure. It also covers payment requirements, error behavior (402), and differentiation from the sibling tool. For a simple lookup tool with good annotations, this is complete.

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

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

Schema description coverage is 100%, so the parameters are already well-documented in the schema. The description does not add additional parameter-specific meaning beyond what origin/destination schemas provide, maintaining the baseline score for full coverage.

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

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

Description opens with 'Get estimated ocean transit times between two ports across all available carriers', which clearly states the verb, resource, and scope. It also distinguishes from the sibling tool by noting that detailed routing with transhipment ports and service codes is handled by shippingrates_transit_schedules.

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

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

Explicitly says 'Use this for quick transit time comparison between ports' and contrasts with 'For detailed routing with transhipment ports and service codes, use shippingrates_transit_schedules instead.' This provides clear when-to-use and alternative guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds critical non-obvious behavior: the payment requirement via x402 and the 402 response when unpaid. It also discloses the return format, providing useful 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?

Every sentence serves a purpose: purpose statement, usage guidance, alternative tool, payment disclosure, and return format. The description is front-loaded with the core action and structured in clear paragraphs with a dedicated 'Returns:' line. No filler.

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

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

With no output schema, the description compensates by specifying the exact return array structure. It also covers payment behavior and distinguishes from a sibling tool. Minor gaps remain, such as how filters interact or empty-result behavior, but overall it is well-rounded for a read-only transit schedule 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 all five parameters with adequate descriptions (e.g., 'UN/LOCODE filter', 'Maximum transit days filter'). The description adds no new parameter-level meaning, so the baseline of 3 applies.

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

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

The description begins with a specific action 'Get detailed transit schedules for a specific carrier' and enumerates the data included (service codes, routing via transhipment ports, transit days, sailing frequency). It explicitly contrasts with sibling tool shippingrates_transit, making its unique scope clear.

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 precisely when to use: 'Use this when you need routing details beyond just transit time' and gives examples. It also names an alternative: 'For a quick transit time comparison across all carriers, use shippingrates_transit instead.' This is explicit when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds valuable context: payment requirement ($0.02/call via x402), failure mode (402 without payment), and the exact return structure (array of objects with fields). This goes well beyond the annotations and enriches the agent's understanding of the tool's 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?

The description is well-structured and front-loaded with the core action, followed by use case, alternatives, payment info, and return format. Every sentence adds meaningful information without redundancy. It is appropriately sized for the tool's complexity.

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

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

Despite lacking an output schema, the description fully covers the return format and payment behavior. It also provides sufficient context for when to use the tool and how it differs from siblings. The schema handles parameter details, so the description's coverage is complete for the tool's complexity.

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

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

The input schema has 100% description coverage for all three parameters (port, x_payment, days_ahead) with clear examples and constraints. The description does not add any parameter-level details beyond what the schema already provides, so a baseline score of 3 is appropriate. The mention of return format is not parameter semantics.

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

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

The description opens with a specific verb+resource: 'Get upcoming vessel arrivals and departures at a specific port.' This clearly distinguishes the tool from transit and transit_schedules alternatives, which are explicitly named. The purpose is unambiguous and differentiated.

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

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

Explicit usage context is provided: 'Use this to check what vessels are expected at a port — useful for booking planning and tracking.' It also names alternatives for other use cases (transit time estimates via shippingrates_transit, service-level routing via shippingrates_transit_schedules), giving clear guidance on when to use this tool vs. its 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?

Despite the annotations already declaring the tool read-only and non-destructive, the description adds meaningful behavioral context: missing cutoff fields remain null or absent and are never inferred. It also discloses the x402 payment requirement and the 402 response when payment is missing, which is 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 front-loaded with the core purpose, followed by usage context, a sibling alternative, payment instructions, and an inline return shape. Every sentence provides distinct, useful information with no filler.

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

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

Even though there is no output schema, the description explicitly lists the return structure with origin, destination, options fields, and coverage. It also covers payment failure behavior, null cutoff handling, and tool differentiation, making 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?

The input schema already provides 100% parameter coverage, including descriptions for origin, destination, carrier, limit, days_ahead, and x_payment. The description largely relies on the schema for parameter meaning, adding context about origin/destination usage but not detailed per-parameter semantics.

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

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

The description opens with a specific verb-resource pairing: 'Get carrier vessel/voyage schedule options between an origin and destination,' and explicitly scopes it to include operational cutoff deadlines. It distinguishes itself from the sibling shippingrates_vessel_schedule by clarifying that this tool adds cutoff details.

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

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

The description explicitly states when to use the tool: 'Use this for booking planning questions that need vessel details, voyage number, transshipment ports, ETA/ETD, and port/SI/VGM cutoffs.' It also provides a direct alternative: 'For port-call monitoring without cutoff details, use shippingrates_vessel_schedule,' making the decision boundary clear.

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