freightgate-mcp-server

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses critical behavioral traits: the payment requirement ($0.05/call via x402), the 402 error response without payment, and the exact return array structure. This adds significant 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?

The description is well-structured with clear sections: definition, usage guidance, payment note, and return format. It is slightly longer than necessary but every sentence carries useful information 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?

The tool is relatively simple, and the description covers purpose, usage, payment, and return format. Without an output schema, the description compensates by listing the return fields. Annotations handle the safety profile. The main gap is that optional parameters are only minimally explained, but the schema partly covers that.

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

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

The input schema already provides descriptions for all four parameters (100% coverage). The description adds some context by explaining what the returned data looks like, which slightly clarifies the meaning of 'service' and 'cargo_type' filters, but it does not add substantial parameter-level semantics 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 gets CFS handling tariffs for LCL cargo at port warehouses, using a specific verb and resource. It distinguishes from sibling tools by explicitly focusing on CFS tariffs and noting it is not relevant for FCL shipments.

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 when-to-use guidance ('Use this for LCL shipments to estimate warehouse handling costs') and a clear when-not-to-use exclusion ('Not relevant for FCL shipments'). However, it does not name alternative tools, so it falls short of the full 5 criteria.

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

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

Beyond the readOnly/idempotent annotations, the description discloses critical runtime behavior: unavailable measurements remain null, unpublished severity stays 'unknown', the certified denominator is specifically USLAX, payment is required (402 if unpaid), and it returns an unchanged API envelope. These are non-obvious traits that significantly aid correct invocation.

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 (four sentences) and front-loaded with the purpose. Each sentence earns its place: purpose, data behavior, payment, and return shape. No filler or 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?

With no output schema, the description compensates by providing the exact return envelope ('{ port, port_name, current_level, days_back, history[] }'). It also covers payment failure, port code specifics, and sibling distinction. For a 3-parameter read-only tool, this is fully contextual.

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 covers all 3 parameters with descriptions, so the baseline is 3. The description adds meaningful context: the port denominator (USLAX), the payment mechanism for x_payment, and the return envelope showing how days_back is used. This exceeds the schema's static definitions.

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

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

The description opens with a specific verb+resource+scope: 'Get certified port-authority congestion measurements for a specific port.' It clearly differentiates from the sibling tool by stating 'For disruption advisories, use shippingrates_congestion_news instead.' This makes the purpose unambiguous.

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

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

The description explicitly names an alternative for a distinct use case ('For disruption advisories, use shippingrates_congestion_news instead'), provides payment prerequisites ('PAID: $0.02/call... Without payment, returns 402'), and explains data availability behavior ('Only fields explicitly published by the authority are populated'). This gives clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, but the description adds rich context: it only includes explicit operational-disruption terms, retains all articles in the collection window, returns an unchanged API array, and never invents alerts. It also discloses payment requirements and the 402 return behavior, going well beyond structured 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 and then provides compact coverage of scope, alternatives, payment, and return shape. The 'current publisher denominator' phrasing is slightly jargon-heavy, but every sentence adds useful information with minimal waste.

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

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

Given no output schema, the description compensates by explicitly stating the returned array shape: '{ headline, summary, source, port_code, severity, published_at }.' It also covers source scope, filtering behavior, payment/error handling, and sibling alternatives, making the tool fully usable without further research.

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 input schema already documents every parameter. The description adds no additional parameter-level meaning beyond what the schema provides, making baseline 3 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 shipping-disruption publications from reviewed official port-authority sources.' This clearly distinguishes it from sibling tools like shippingrates_congestion and shippingrates_risk_score, and the title 'Shipping Disruption News' reinforces the 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?

Explicit alternatives are provided: 'For quantitative measurements, use shippingrates_congestion. For route-level risk scoring, use shippingrates_risk_score.' This tells the agent when not to use this tool and where to redirect, which is exactly the desired 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 annotations (readOnly, idempotent, non-destructive), it details return fields, default charge-type priority, storage coverage gaps, explicit 'no data' error behavior, live-derived error messages, payment cost, and 402 handling. 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?

Well-structured with clear sections: purpose, usage, comparison, storage nuance, payment, and return format. Slightly verbose in the storage sentence but every part 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?

Despite no output schema, the description covers all decision-relevant aspects: scope, charge types, payment requirements, error semantics, and return shape. Agent has sufficient info to select 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 covers all 7 parameters (100%), so baseline is 3. Description adds meaning for charge_type='storage' override, default priority engine, and payment context, providing value 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 opens with 'Calculate demurrage and detention (D&D) costs for one carrier in one country' — a specific verb, resource, and scope. It explicitly contrasts with shippingrates_dd_compare for cross-carrier comparison, making it distinct from siblings.

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

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

It provides explicit guidance: 'Use this when the user needs a detailed cost breakdown for a specific carrier' and names the alternative tool for comparing all carriers. Also explains when to use charge_type='storage' and its 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: the tool is PAID ($0.25/call via x402 with payment instructions if unmet), returns a sorted array, and explains the response format. No contradictions with annotations.

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

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

The description is five sentences with no filler. The first sentence states the core function, the second explains use cases, the third differentiates from a sibling, the fourth covers payment, and the fifth describes the return value. 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?

The description covers purpose, usage, payment behavior, alternative tools, and the return format (array of objects with fields, sorted by total_cost). There is no output schema, so the description carries the burden of explaining the response, which it does, though it doesn't elaborate on the 'slabs' field structure or potential error cases. Overall, it's sufficiently complete for a paid 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 description coverage is 100%, so the baseline is 3. The description reinforces the meaning of the three required parameters (country, container type, days) but does not add significant new semantic detail beyond the schema, aside from clarifying that 'days' refers to detention days in the first sentence.

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 with a specific verb ('Compare') and resource ('demurrage and detention costs across ALL available carriers'), and explicitly distinguishes it from the sibling tool shippingrates_dd_calculate by pointing to that alternative for single-carrier comparisons. This is more than adequate.

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

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

Explicitly states when to use: for freight procurement and carrier selection, answering 'which carrier has the cheapest D&D in this country?'. It also directly says to use shippingrates_dd_calculate instead for a single carrier's detailed breakdown, providing a clear when-not scenario.

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 discloses that arrival_date is user-supplied and not carrier-confirmed (data_basis=user_supplied_arrival), a critical accuracy caveat. It also discloses the paid access requirement ($0.10/call, 402 without payment), the storage charge_type special case with thin coverage, and the charge_family response disambiguation.

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 comprehensive but well-structured: it front-loads the core purpose, then addresses use case, caveats, payment, and return fields in logical order. While slightly long, every sentence adds substantive information.

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

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

With 8 parameters and no output schema, the description compensates by explicitly listing the return fields, covering the payment flow, and noting coverage limitations. The contrast with dd_calculate and the data_basis caveat make it complete for an agent to invoke confidently.

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 per-parameter descriptions, setting a baseline of 3. The description adds value by explaining the arrival_date clock semantics, the x_payment requirement tie-in, and the charge_type override behavior, pushing it to 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 opens with a precise verb and resource: given container details, it reports free days remaining, first chargeable day, per-diem, and cost projection. It explicitly contrasts with shippingrates_dd_calculate, which answers a fixed number of days, making the tool's niche 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 explicitly states 'Use this to answer how long until this container starts costing demurrage, and how much per day?' and names shippingrates_dd_calculate as the alternative for fixed-day calculations, with a note that they share the same tariff engine. This gives clear when-to-use and when-not-to-use 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 declare readOnly, idempotent, and non-destructive behavior. The description adds crucial context beyond those hints: it discloses that optional operational attributes (GPS, rail, operator, capacity) remain null unless certified by a separate source, and it details the payment requirement: 'PAID: $0.02/call via x402... Without payment, returns 402 with payment instructions.' It also explains the response shape ('Returns the existing facility response shape...'). This provides rich behavioral insight beyond the annotations.

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

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

The description is organized into three clear paragraphs: purpose, usage context, payment, and return shape. Every sentence adds value without redundancy. It front-loads the primary action and then covers crucial operational details (payment and null attributes) in an efficient, 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?

The tool has no output schema, but the description compensates by explaining the response shape: 'Returns the existing facility response shape, with certified code/name/type and null for unsupported optional attributes.' It also covers the payment failure mode (402), the source (official ICEGATE), and the limitation on optional data. This is complete for a directory lookup tool, though a bit more detail on the response fields would be ideal.

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

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

The input schema covers 100% of parameters with individual descriptions, so the baseline is 3. The description adds meaningful context by stating that the current edition does not assert GPS, rail, operator, or capacity data, which clarifies how the rail_connected filter and output fields behave. It also clarifies that optional operational attributes will be null, not simply absent or unknown.

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

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

The description opens with a specific action: 'Search India's current official ICEGATE Inland Container Depot (ICD) and Container Freight Station (CFS) directory' and clarifies the search keys: code, name, and type. This clearly distinguishes the tool as a facility directory lookup compared to sibling tools like shippingrates_inland_search or shippingrates_cfs_tariffs.

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

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

The description explicitly states the intended use: 'Use this to resolve an official ICEGATE ICD/CFS code or facility name.' It implies that this tool is for validated, official directory lookups and not for unverified operational attributes. However, it does not explicitly contrast with alternative sibling tools or list exclusions for 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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: 'updated on ECB working days,' 'unsupported currencies fail closed,' 'FREE — no payment required,' and the exact return format. This exceeds what annotations provide and gives the agent a clear model of expected 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 efficiently structured in two short paragraphs: the first delivers the core action, and the second covers usage context, update frequency, failure mode, cost, and return value. Every sentence earns its place 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 two-parameter, read-only tool with strong annotations and no output schema, the description is comprehensive. It explains the source (ECB), freshness, failure behavior, cost, return format, and a clear usage scenario. No important information is missing for an agent to select and invoke this 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?

The input schema fully documents both parameters with descriptions and examples, covering 100% of the parameters. The description adds a partial list of supported currencies and the fail-closed behavior, but does not add meaningful meaning beyond the schema. Baseline 3 is appropriate because 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 opens with a specific verb+resource: 'Get the current certified ECB reference rate between two supported currencies.' This clearly states the tool's function and distinguishes it from all shipping-related sibling tools, none of which handle currency exchange. It also provides a concrete use case for shipping cost conversion.

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 to normalize costs from different carriers/countries to a common currency for comparison.' It also notes the update frequency and fail-closed behavior. However, it does not explicitly mention when-not to use it or name alternatives, though no sibling tool performs FX conversions.

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 key behavioral details: sorted cheapest first, ramp/door rates never mixed, delivery_mode defaults to 'ramp', payment required ($0.08/call via x402), returns 402 without payment, and return format. No contradiction with annotations.

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

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

Four sentences, each earning its place: purpose, usage alternatives, payment/behavioral constraints, and return format. Front-loaded main purpose.

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

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

Complete for an 8-parameter tool: covers use case, alternatives, payment, behavioral constraints, and return format. Since no output schema exists, the explicit return field list is valuable.

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 parameters have descriptions. The description adds minimal new parameter semantics beyond the schema—it repeats delivery_mode default and mentions return fields, but does not clarify additional parameter meaning. Baseline 3 per rubric.

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 the tool's function: 'Compare inland haulage rates across ALL available carriers for a port-to-ICD/city pair — sorted cheapest first.' It also distinguishes from siblings by naming shippingrates_inland_haulage for single-carrier rates and shippingrates_inland_search for route discovery.

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

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

Provides explicit usage guidance: 'Use this for carrier selection on inland legs — answers "which carrier offers the cheapest trucking/rail from port X to city Y?"' It explicitly names alternatives and when to use them, and clarifies delivery_mode behavior.

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 readOnlyHint and idempotentHint annotations, the description discloses critical behavioral traits: the payment requirement ($0.05/call via x402), the consequence of non-payment (returns 402 with payment instructions), and the return payload structure. This adds substantial context that annotations do not cover, such as the exact array fields and the fact that rates are route-specific.

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 a clear purpose, then gives usage context, lists alternatives, states the payment/error behavior, and ends with the return format. Every sentence provides actionable information 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?

Given the tool has 8 parameters and no output schema, the description adequately compensates by providing the output array shape, clarifying the payment flow, and explaining how this tool fits with its siblings. It is complete enough for an agent to select and invoke the tool correctly without needing additional documentation.

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

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

The input schema already has 100% description coverage for all 8 parameters, including enums and examples. The description adds minimal extra meaning, merely reinforcing that origin and destination are the required route identifiers and mentioning container type in prose. This matches the baseline of 3 for high schema coverage; it does not meaningfully compensate or elaborate 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 verb, resource, and scope: 'Get inland haulage (trucking/rail) rates for moving containers between a port and an inland location.' It also explicitly distinguishes itself from sibling tools by naming shippingrates_inland_search and shippingrates_inland_compare, making the purpose 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 provides explicit usage guidance: 'Use this when you know the specific origin port and destination and need rate quotes.' It also tells when to use 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 addresses both when-to-use and 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 already indicate a safe, read-only, idempotent operation, but the description adds critical behavioral context beyond that: payment requirements ('PAID: $0.03/call via x402'), failure behavior ('Without payment, returns 402 with payment instructions'), and a clear return format ('Array of { origin, destination, mode, container_types, icd_code }'). This is valuable transparency not present in the schema or annotations alone.

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 4 sentences long, each with a distinct purpose: purpose statement, usage example, payment/pricing note, and return type. No filler or redundant phrasing. It is front-loaded with the core action, then provides necessary context, making it both concise and well-structured.

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

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

Despite having 6 parameters and no output schema, the description covers all essential context: it states the tool's scope, includes a realistic example, explains payment and error behavior, and describes the return shape. It also clarifies how it differs from two sibling tools. This is a complete and self-contained guide for the 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?

Input schema covers all 6 parameters with complete descriptions (100% coverage), so baseline is 3. The description adds a concrete usage example—'search "ahmedabad" to find routes from Nhava Sheva to Ahmedabad via Maersk'—that clarifies how the keyword parameter is intended to be used. While the schema already defines each field, the example provides practical meaning, justifying a 4 rather than a 3.

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 'Search for available inland transport routes (road/rail haulage) from port to inland destinations for a specific carrier,' which precisely states the action, resource, and scope. It also distinguishes itself from siblings by explicitly pointing to shippingrates_inland_haulage for rate quotes and shippingrates_inland_compare for comparisons, 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?

The description gives direct guidance: 'Use this to discover what haulage routes a carrier offers in a country.' It further clarifies exclusions: 'For actual haulage rate quotes, use shippingrates_inland_haulage. For cross-carrier rate comparison, use shippingrates_inland_compare.' This is explicit when-to-use and alternative tooling, meeting the highest bar.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable context beyond annotations: 'FREE — no payment required', 'reviewed' (trusted data), 'live D&D coverage' (current availability), and the exact return structure. It does not contradict any annotation.

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

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

The description is compact and well-organized: a clear first sentence for the main action, a short usage sentence, a cost note, the return type, and related tools. Every sentence serves a purpose 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, the description covers all necessary context: purpose, use case, cost, return format, and related alternatives. It is self-contained despite the absence of an output schema, and the sibling tool landscape is addressed via explicit pointers.

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 zero parameters, so the baseline is 4. No parameter explanations are needed. The description instead clarifies the output meaning (shipping_line, country, records), which is useful given no output schema exists.

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 a specific verb ('List') and resource ('reviewed shipping-line identities'), with qualifiers ('currently have live D&D coverage', 'per-country record counts') that precisely define scope. It distinguishes from siblings by explicitly framing this as a discovery step before querying a tariff tool.

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

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

The description says 'Use this to discover which carrier-country D&D combinations are currently available before querying a tariff tool' and explicitly names alternatives: 'Use shippingrates_stats for aggregate totals, shippingrates_search for keyword-based discovery.' This provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate readOnly and idempotent. The description adds the paid nature ($0.05/call via x402) and the 402 error without payment, which is not in annotations. It also discloses the return format (array of charge objects), adding useful behavioral context beyond the structured fields.

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 line breaks: purpose, usage, payment, and return format. Every sentence earns its place, with no redundant content. It is front-loaded with the primary purpose and efficiently conveys all necessary information.

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

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

The description covers purpose, usage, payment, and return format. However, the optionality of port_code is not clarified in the description: it says 'at a port' but port_code is not required, leaving ambiguity whether results are for a specific port or all ports in a country. This minor gap prevents a perfect score.

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 each parameter already described. The tool description itself does not add parameter-level meaning beyond what the schema provides, so it earns the baseline of 3 without needing compensation.

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 'Get local charges at a port for a specific carrier' with concrete examples (THC, documentation fees, seal fees). It distinguishes itself from siblings by explicitly mentioning complementary tools (dd_calculate, total_cost) and focusing on port-specific charges rather than broader shipping costs.

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: 'when calculating total shipping costs at origin or destination.' It also names alternatives and how to combine: 'Combine with shippingrates_dd_calculate for a complete port cost picture, or use shippingrates_total_cost for an all-in-one landed cost estimate.' This gives clear decision support.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context beyond these: the paid nature ($0.01/call via x402), the 402 response without payment, and the exact return object shape. No contradictions with annotations.

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

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

The description is concise and well-structured with four purposeful sentences. It front-loads the core purpose, then adds usage guidance, payment terms, and return format. No filler or redundancy; every sentence carries necessary information.

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

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

Despite no output schema, the description explicitly documents the return fields, making the contract complete. It covers what the tool does, when to use it, the payment and error behavior, and the data shape. Given the low complexity (1 required param), this is 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?

The input schema covers both parameters well (100% coverage), including examples for 'code' and a description for 'x_payment'. The description adds context by explaining the payment requirement ('PAID: $0.01/call via x402... Without payment, returns 402') and clarifies that 'code' is an UN/LOCODE, reinforcing schema examples. This elevates it slightly above the 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 uses a specific verb 'Look up' with a specific resource ('port details by UN/LOCODE') and lists concrete fields (name, country, coordinates, timezone, terminal facilities). It clearly distinguishes itself from sibling tools by scoping to LOCODE lookups and explicitly directing unknown-code searches to 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 ('validate port codes or get port metadata') and provides a clear alternative: 'If you don't know the UN/LOCODE, use shippingrates_search with the port or city name first.' This is direct, actionable guidance for tool selection.

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

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

Annotations already declare read-only and idempotent behavior. The description adds valuable behavioral context: payment requirement ($0.03/call via x402), 402 error response without payment, and fallback behavior for unsupported lanes. It also documents the return structure, which is essential 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: a clear first sentence, then context, payment, and return format. It avoids unnecessary prose. The long return type listing is justified by the lack of an output schema and provides essential information for the agent.

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 (payment, optional filter, detailed return shape), the description covers all critical aspects: purpose, payment, error behavior, unsupported lanes, and return format. It also gives an alternative when a different type of estimate is needed. This is sufficient 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?

All parameters have descriptions in the input schema (100% coverage), including UN/LOCODE examples and container type filter. The description's 'between two ports' and 'optionally filtered by container type' align with but do not significantly extend the schema. With full schema coverage, 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 'Get current certified freight benchmark observations between two ports, optionally filtered by container type' — a precise verb and resource. It further distinguishes itself by clarifying these are 'official published market indices, not carrier spot quotes or contracted rates' and explicitly points to shippingrates_total_cost as the alternative for multi-component estimates.

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

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

It provides explicit when-to-use context (benchmark observations between ports), what it is not (spot quotes/contracted rates), and names a specific alternative for multi-component estimates (shippingrates_total_cost). It also tells the agent that unsupported lanes return an empty rates array, helping set expectations.

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 critical behavioral context beyond the annotations: a payment requirement ($0.01/call via x402), the 402 response without payment, and the full return object structure. This is essential for the agent to invoke the tool correctly and handle failures, and it does not contradict the read-only/idempotent 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 tightly written: a concise purpose statement, a one-sentence usage guideline, and a terse payment/return specification. Every sentence adds distinct value, and the structure is logical 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?

For a read-only data tool with no output schema, the description provides the return structure, payment requirement, and error behavior, covering the essential operational details. Minor omissions like case-sensitivity of country codes do not significantly impact usability.

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?

All three parameters are fully documented in the input schema (country code format, limit range/default, x_payment header). The description does not add further parameter details, but given 100% schema coverage, the 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 tool's function with a specific verb ('Get'), resource ('recent shipping regulatory updates and compliance requirements'), and scope ('for a specific country'). It also lists concrete content areas (customs, documentation, trade restrictions) and is easily distinguished from sibling tools, none of which focus on regulatory updates.

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 to stay current on regulatory changes that may affect shipments to/from a country,' providing a clear use case. It does not mention alternatives, but the tool is unique among siblings, so explicit exclusions are unnecessary.

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 idempotent, but the description adds crucial context: the PAYG payment model ($0.02/call), the 402 failure mode with payment instructions, the behavior of returning nulls for unpublished fields, and the return envelope fields. This goes well beyond what annotations provide, with no contradiction.

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

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

The description is four sentences, each earning its place: purpose, usage, payment, and return envelope. It is front-loaded with the verb, avoids fluff, and is highly scannable.

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

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

Despite having no output schema, the description fully covers the return value ("unchanged API reliability envelope with source, period, freshness, and published metric fields"), the failure mode (402), limitations (null fields), and payment requirements. This is complete for a simple, read-only data access tool with one required parameter.

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 provides full descriptions for all three parameters, including the line enum and trade_lane example. The description adds no parameter-specific details beyond what the schema already explains, so the baseline of 3 is appropriate.

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

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

The description opens with a specific verb and resource: "Get the latest certified public schedule-reliability highlights for a carrier." This clearly distinguishes the tool from sibling tools like shippingrates_rates or shippingrates_congestion, which target different data. The title 'Schedule Reliability' reinforces the 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 explicitly states when to use it: "Use this for carrier selection and high-level benchmarking." It also notes a limitation (only published metrics returned) and the payment requirement. However, it does not mention alternatives or provide when-not-to-use guidance, so it falls short of a full 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?

The description goes well beyond the readOnly/idempotent/non-destructive annotations by disclosing determinism, zero-scoring for unknown inputs, no-result behavior for unsupported routes, immutable UN/LOCODE mapping, payment requirement and 402 response, and the unchanged API result shape. No contradictions with annotations.

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

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

The description is compact and front-loaded with the core purpose, followed by essential behavioral details, payment info, and return shape. Every sentence adds value without redundancy, making it easy to scan and apply.

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

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

Given the tool's complexity (paid, deterministic scoring, multiple data sources, specific behavior for unsupported routes), the description covers all necessary aspects: scoring logic, source inputs, mapping, alternatives, payment, and the response shape. Without an output schema, the explicit return shape is essential and provided.

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 each parameter, so the baseline is 3. The description adds meaningful context: origin/destination define the route, unknown inputs contribute zero points, and x_payment is the x402 payment proof header, which enriches understanding beyond the schema alone.

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

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

The description uses a specific verb ('Get') and resource ('deterministic route-risk score'), clearly scoped to port congestion and official advisories. It explicitly distinguishes itself from siblings by directing users to shippingrates_congestion for exact measurements and shippingrates_congestion_news for advisory detail.

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

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

It provides explicit when-to-use guidance by contrasting with related tools: 'For exact measurements, use shippingrates_congestion. For advisory detail, use shippingrates_congestion_news.' It also explains the behavior for unsupported routes, making selection criteria unambiguous.

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

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

While annotations already declare safe read-only behavior, the description adds meaningful behavioral context: search scope (certified/reviewed/published data), the no-fallback policy for uncertified/legacy data, that it is free, and the return structure. This goes well beyond the annotations. 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: opens with a clear action sentence, then elaborates on scope and exclusions, followed by return format and alternative tools. Every sentence earns its place; no redundancy or filler. It is appropriately concise for the information it conveys.

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, search scope, exclusions, return format, and alternative tools. For a single-parameter keyword search, this is thorough. The return structure is explicitly given, so the agent knows what to expect even without an output schema. The tool's complexity is fully addressed.

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 complete parameter documentation (100% coverage) with examples. The description further enriches semantics by enumerating the entity categories the keyword can match (port codes/names, carrier identities, transit services, local charges), giving the agent a clearer model of valid inputs. 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 uses a specific verb ('Search') and resource ('current customer-published ShippingRates datasets'), and further distinguishes itself by listing matched entity types (port codes/names, carrier identities, transit services, local-charge names/carriers) and explicitly contrasting with sibling tools (shippingrates_port, shippingrates_lines). This makes the tool's unique purpose 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?

The description explicitly names alternatives (shippingrates_port for structured port lookup by UN/LOCODE, shippingrates_lines for full carrier listing) and explains when they are preferable. It also states exclusionary behaviors ('Uncertified families remain empty and legacy rows are never used as a fallback'), providing clear when-to-use vs. when-not-to-use guidance.

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

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

Beyond the read-only and idempotent annotations, the description discloses critical behavioral nuance: counts include only certified publishable dependencies, uncertified families report zero instead of falling back to legacy rows, and the countries/shipping_lines fields are distinct counts. Also notes the tool is free. This significantly enhances agent understanding of edge-case 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 compact and well-structured, with the main purpose in the first sentence, followed by usage context, behavioral details, the return shape, and related tools. Every sentence carries unique value, and there is no 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 that there is no output schema, the description provides a full return structure with field names and type notation (ISO datetime). It also covers special fallback behavior, the FREE aspect, and direct pointers to related tools, making the description complete for an agent to invoke this tool without additional context.

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

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

The tool has zero parameters, so the description cannot add parameter-specific meaning beyond the empty schema. The rubric sets a baseline of 4 for zero-parameter tools. The description does clarify the semantics of returned fields (e.g., distinct counts), which partially compensates for the lack of output schema, but since parameters are nonexistent, a perfect score is not warranted.

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 counts from ShippingRates customer-published datasets,' which clearly states the specific verb (get), resource (counts from datasets), and scope. It also explicitly differentiates from related tools by naming shippingrates_lines and shippingrates_search as alternatives, 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?

The description explicitly instructs 'Use this before calling data tools' and provides direct alternatives: 'Use shippingrates_lines for per-carrier breakdowns, shippingrates_search for keyword discovery.' This gives clear when-to-use and when-not-to-use guidance relative to 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, destructiveHint=false, and idempotentHint=true. The description adds valuable behavioral context beyond those: payment is required ($0.02/call via x402), failure returns 402 with payment instructions, and the return format is explicitly stated as an array of surcharge objects. This extra information provides practical operational transparency without contradicting 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 well-organized and front-loaded: it starts with the core action, lists examples, gives the use case, explains the context, provides an alternative, and ends with payment and return details. Every sentence carries distinct information, and the text 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 no output schema, the description explicitly defines the return structure (array of objects with specific fields). It also covers payment prerequisites, error behavior, and the relationship to base freight rates. For a tool with 4 params and 100% schema coverage, this description is fully sufficient for an agent to select and 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 description coverage is 100%, so the baseline is 3. The description does not add significant parameter-level detail; it only mirrors the schema concepts (carrier, country, direction). It does not explain syntax, defaults, or constraints beyond what the schema already provides. Thus the description adds minimal semantic value over the structured schema.

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

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

The description opens with 'Get carrier-specific surcharges', a specific verb+resource combination. It enumerates concrete surcharge types (BAF, CAF, PSS, EBS) and clearly distinguishes from sibling tools by focusing on surcharges rather than base rates or total cost. The explicit mention of shippingrates_total_cost as an alternative further sharpens the tool's unique role.

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

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

The description directly states when to use the tool: 'Use this to understand surcharge exposure for a carrier in a specific country/direction.' It also provides an explicit alternative: 'For a complete cost breakdown, use shippingrates_total_cost which includes surcharges automatically.' This gives clear decision guidance relative to 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?

Beyond the readOnly/idempotent annotations, the description discloses critical behavioral traits: partial results, market index vs. carrier quote distinction, mandatory vs. additional cost categorization, and the 402 payment failure mode. This is rich, non-obvious context that annotations alone do not 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 long but every sentence earns its place: purpose, rationale, payment, output structure, and an IMPORTANT clarification. It is front-loaded with the core function and then layers caveats and details in a logical order, making it 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?

For a tool with no output schema, the description fully compensates by explaining the return shape, covering key fields, and highlighting the mandatory vs. additional cost distinction. It also addresses partial results and the need to inspect verification flags, making it self-sufficient for an agent to understand what to expect and how to interpret results.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add substantial per-parameter meaning beyond translating 'demurrage/detention exposure' to the detention_days parameter, but the schema already fully documents each parameter with descriptions and enums.

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

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

The description opens with a specific verb ('Calculate') and a well-defined resource ('published multi-component shipping-cost estimate'), listing the exact components included. It also distinguishes itself from siblings by pointing to individual component tools for specific needs.

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 'For individual components, use shippingrates_rates, shippingrates_surcharges, shippingrates_local_charges, and shippingrates_dd_calculate,' providing clear alternatives. Also notes the payment requirement and cautions that the result can be partial, establishing appropriate usage expectations.

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 discloses the payment requirement (PAID $0.02/call via x402), the failure behavior (returns 402 without payment), and the return shape. This is valuable behavioral context that annotations do not cover.

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 guidance, sibling distinction, payment details, and return format. Every sentence contributes necessary information without 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 simple two-required-parameter lookup tool with no output schema, the description is complete: it covers the function, usage boundaries, payment requirements, return format, and alternative tool. No important context 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?

The input schema has 100% coverage with clear descriptions and examples for origin and destination, so the baseline is 3. The tool description does not add per-parameter details beyond what the schema already provides, though it does frame the parameters as 'between two ports'.

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 estimated ocean transit times between two ports across all available carriers.' It clearly distinguishes itself from the sibling tool shippingrates_transit_schedules by noting that this is for quick comparison while the sibling handles detailed routing with transhipment ports and service codes.

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 the tool ('quick transit time comparison between ports') and names the alternative for more detailed needs ('use shippingrates_transit_schedules instead'). This gives the agent clear decision-making 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 annotations (readOnlyHint=true, idempotentHint=true), the description discloses the paid nature ($0.03/call via x402), the payment mechanism (USDC on Base or Solana), and the 402 error behavior when unpaid. It also specifies the return shape since there is no output schema, which is valuable 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?

The description is concise and well-structured: first sentence states the core purpose, second paragraph gives usage guidance and alternatives, third paragraph covers payment and return shape. Every sentence earns its place 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?

Despite lacking an output schema, the description provides a clear return structure, payment requirements, and tool alternatives. The five parameters are fully covered by the schema, and the usage context is complete for this tool type.

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 coverage is 100% and each parameter already has a clear description (e.g., carrier SCAC code, origin/destination UN/LOCODE filters). The tool description does not add significant parameter semantics beyond what the schema provides, so a baseline of 3 is appropriate.

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

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

The description opens with a specific action ('Get detailed transit schedules') and enumerates the key output dimensions (service codes, routing via transhipment ports, transit days, sailing frequency). It clearly distinguishes from the sibling tool shippingrates_transit by contrasting detailed routing versus quick transit-time comparison.

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

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

The description explicitly states when to use this tool ('when you need routing details beyond just transit time') and directs users to the alternative tool ('For a quick transit time comparison across all carriers, use shippingrates_transit instead'). This is excellent usage guidance with a named 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, and description adds a unique behavioral trait: the tool is PAID with $0.02/call via x402 and returns 402 when unpaid. This explains a critical non-standard behavior not available from annotations. It also clarifies the return fields structure. Minor gap: doesn't mention pagination or rate limits, but annotations cover safety.

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

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

Description is well-organized: a one-sentence purpose, a context paragraph, explicit sibling differentiation, payment note, and return format. It uses bullet-like structure via line breaks, is front-loaded with the main purpose, and every sentence adds distinctive info. Efficient and uncluttered.

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 provides the return array structure (vessel_name, carrier, voyage, eta, etd, service, from_port, to_port). It covers payment requirements, default behavior, and alternate tools. For a list-type tool with 3 params and full schema coverage, this is complete enough for agent use.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the purpose of the main 'port' parameter (examples given in schema) and by noting the default for days_ahead (14) which is not in the schema, and clarifying the x_payment header. It doesn't add syntax details but compensates with 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?

The description clearly states it gets upcoming vessel arrivals/departures at a specific port, with a specific verb ('Get') and resource ('vessel arrivals and departures'). It lists specific return fields and distinguishes itself from sibling tools like shippingrates_transit and shippingrates_transit_schedules by 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 use cases ('useful for booking planning and tracking') and explicit alternatives for different needs ('For transit time estimates... use shippingrates_transit. For detailed service-level routing, use shippingrates_transit_schedules.'). This clearly guides when to use this tool vs alternatives.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds crucial behavioral context beyond that: missing cutoffs remain null/absent and are not inferred, and the payment requirement (PAID: $0.03/call via x402, 402 if not paid) is disclosed. This is significant for an agent to avoid failed calls.

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: first sentence states the core function, second gives usage context, third explains missing data behavior, fourth provides an alternative tool, fifth covers payment, and sixth summarizes the return structure. Every sentence adds essential information with 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 having no output schema, the description includes a sample return structure ('Returns: { origin, destination, options: Array<{...}>, coverage }'), which is highly informative. It also covers payment prerequisites, data-fidelity expectations, and a clear alternative, making the description comprehensive for a 6-parameter 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% (all parameters have descriptions in the schema), so the baseline is 3. The description adds no parameter-level details beyond what the schema already provides, but it does mention origin/destination in the opening sentence. It does not harm or add extra meaning to param usage.

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

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

The description opens with a specific verb ('Get') and a clear resource ('carrier vessel/voyage schedule options between an origin and destination') that includes cutoff deadlines. It explicitly distinguishes itself from the sibling 'shippingrates_vessel_schedule' by mentioning cutoffs, making the tool's purpose 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 states exactly when to use this tool ('Use this for booking planning questions that need vessel details, voyage number, transshipment ports, ETA/ETD, and port/SI/VGM cutoffs') and provides a direct alternative: 'For port-call monitoring without cutoff details, use shippingrates_vessel_schedule.' This is explicit and actionable.

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