freightgate-mcp-server

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

Annotations already indicate read-only, idempotent, non-destructive behavior. Description adds that it's a paid API ($0.05/call via x402) and returns 402 without payment. Also lists return 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?

Five sentences, each adding distinct value: purpose, usage, return fields, payment info, and return structure. 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?

Despite lacking an output schema, the description provides return fields. It covers purpose, usage, payment, and differentiation from FCL. Context signals show 4 params with 1 required, and description adequately supports 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 baseline is 3. Description re-iterates parameter context (e.g., UN/LOCODE port code) and adds return structure details, but does not significantly enhance 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?

Title and description clearly specify the tool retrieves CFS handling tariffs for LCL shipments. It distinguishes from siblings by mentioning it's not for FCL, and explicitly lists the types of charges returned (per-unit rates, minimum charges, storage fees).

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

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

Explicitly states 'Use this for LCL shipments to estimate warehouse handling costs' and 'Not relevant for FCL shipments.' Also includes payment instructions and error response without payment.

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 tool is safe. The description adds important behavioral traits: the tool is paid ($0.02/call via x402) and returns a specific JSON structure, with a note on payment failure (returns 402 with instructions). 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 structured into four concise sections: what it returns, use case with alternative, payment info, and return format. Each sentence adds value, though the mention of D&D costs could be slightly trimmed. Front-loaded with key action and resource.

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 moderate complexity (3 params, no output schema but return fields listed), the description covers purpose, usage guidelines, payment, and expected output. Annotations provide safety profile. Sibling context given. No missing critical 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?

Schema coverage is 100% with clear descriptions for all three parameters (port, days_back, x_payment). The tool description does not add parameter-specific details beyond the schema; it mentions port code examples in the description of port parameter, but that is already in the schema. Baseline 3 since schema already 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 starts with 'Get port congestion metrics' and lists specific metrics (vessel waiting times, berth occupancy, delay trends), clearly indicating the resource and action. It also distinguishes from the sibling tool 'shippingrates_congestion_news' by mentioning its use for disruption news instead.

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 ('assess port efficiency and anticipate detention risk') and provides a clear alternative ('For shipping disruption news... use shippingrates_congestion_news instead'). This covers both usage and exclusion criteria.

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

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

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint), description adds payment cost ($0.02/call via x402), failure behavior (returns 402 without payment), and return format (array of objects with fields). 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?

Highly concise: 3 sentences for core purpose, 2 for guidance, 1 for payment, 1 for return format. Each sentence adds value without redundancy.

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

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

Covers purpose, usage, behavioral traits, return format, and payment. No output schema, but return format is described. Could be enhanced with an example, but adequate for selection and invocation.

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

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

Schema coverage is 100% with descriptions for all 5 parameters. Description adds context on payment parameter and implicitly covers others, but doesn't add much beyond schema. Still, it's clear and useful, justifying a score above baseline.

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

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

Description uses specific verb 'Get' and resource 'shipping disruption news' with multiple qualifiers: aggregated from 7 trade press sources, port tagging, severity classification, and list of covered events (Hormuz Strait, Red Sea/Houthi, etc.). It clearly differentiates from siblings like shippingrates_congestion and shippingrates_risk_score.

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 ('situational awareness, 'are there any active disruptions affecting my route?') and when not, with direct references to alternative tools for quantitative metrics and risk scoring.

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

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

Discloses payment requirement ($0.10/call), 402 response if unpaid, and return structure. Annotations already indicate readOnly and idempotent, and description does not contradict them; adds valuable 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?

Concise, well-structured: purpose, usage, output, alternative, payment info. Every sentence is necessary and efficiently communicates key 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, description fully describes return format including slab structure. Covers payment, idempotency, and required parameters. Complete for an agent to use 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%, so description adds limited parameter detail beyond schema. Does confirm mapping parameters to return fields but no extra semantics. Baseline 3 is appropriate.

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

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

Description clearly states it calculates D&D costs for one carrier in one country, specifies output (free days, per-diem rates, total cost), and distinguishes from sibling tool shippingrates_dd_compare by 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?

Explicitly says 'Use this when the user needs a detailed cost breakdown for a specific carrier' and provides alternative for comparison across carriers. Also includes payment 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?

Description adds behavioral context beyond annotations: returns side-by-side comparison sorted cheapest first, includes payment info and 402 error handling. No contradictions with annotations.

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

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

Efficiently structured: purpose first, then usage guidance, alternatives, payment, and return format. No wasted words.

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

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

Fully explains functionality, return format, payment requirements, and error handling. With 4 parameters and no output schema, description provides complete contextual coverage.

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

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

Schema covers all 4 parameters with descriptions (100% coverage). The description adds value by explaining how parameters combine for cross-carrier comparison, but baseline 3 is appropriate; +1 for practical contextualization.

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?

Title and description state it compares demurrage and detention costs across all carriers for the same country, container type, and days. Clearly distinguishes from sibling tool shippingrates_dd_calculate by specifying 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?

Explicitly states use case: freight procurement and carrier selection, and directly names the alternative tool for single carrier details.

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

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

Annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false) already indicate safety. The description adds critical payment behavior: cost per call, required currency and network, and the 402 response for non-payment. Also describes the return array format with field names. No contradictions.

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

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

Very concise: three sentences plus a bullet point listing return fields. Information is front-loaded (purpose first, then usage, then payment, then output). No unnecessary words.

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

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

Given the 5 optional parameters, no output schema, and many sibling tools, the description covers all needed context: what the tool returns, payment requirements, and integration hint with inland_haulage. Sufficient for an agent to decide and invoke correctly.

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

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

Input schema has 5 parameters with full descriptions (100% coverage). The description adds context by listing the return fields (code, name, type, state, etc.), indirectly clarifying parameter usage. No additional parameter semantics needed 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 the verb 'Search' and the resource 'India's Inland Container Depot (ICD) and Container Freight Station (CFS) facility directory', listing specific data fields. It distinguishes itself from sibling tools like shippingrates_inland_haulage by suggesting combined use.

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: 'to find facilities near an inland destination in India, or to check if a specific ICD/CFS has rail connectivity.' It mentions a related sibling tool for inland logistics planning, but does not explicitly list when not to use or alternative tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by noting it is FREE, rates are updated daily, and the return format { from, to, rate, timestamp }. No contradictions.

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

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

The description is concise and well-structured. It front-loads the main purpose, then provides usage context, pricing, and return format in a clear, no-waste manner.

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 tool with 2 parameters and no output schema, the description provides complete information: purpose, usage, return format, update frequency, and cost. Sufficient for an agent 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 description coverage is 100%, with each parameter (from, to) already having descriptions. The tool description does not add additional parameter semantics beyond what the schema provides.

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

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

The description clearly states the tool's purpose: 'Get current exchange rate between two currencies.' It provides specific currency examples and distinguishes it from sibling tools, as no other sibling deals with currency exchange.

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 a concrete use case: 'converting shipping costs quoted in different currencies... to a common currency for comparison.' It does not explicitly state when not to use or list alternatives, but the context is clear.

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

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

Adds payment info ($0.08/call via x402, 402 failure) and return format details beyond annotations. Annotations already cover readOnly, idempotent, non-destructive. No contradictions.

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

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

Three concise paragraphs: purpose, usage guidance, payment and return info. Front-loads key action and sorting. No wasted words.

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

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

Covers purpose, usage, payment, and return format. Lacks error cases (e.g., no rates found) but overall adequate given parameter count and no output schema.

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

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

Schema coverage is 100%, but description adds examples (UN/LOCODE for origin) and defaults (container_type default 20GP), enhancing understanding 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 compares inland haulage rates across all carriers for a port-to-ICD/city pair, sorted cheapest first. It distinguishes from sibling tools by referencing shippingrates_inland_haulage (single carrier) and shippingrates_inland_search (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?

Explicitly states when to use (carrier selection on inland legs) and when not to (single carrier rates or route discovery), with direct references to 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?

Adds payment requirement and error response beyond annotations, which already indicate idempotent and read-only behavior. Describes return format. No contradictions.

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

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

Six sentences, front-loaded with purpose, then usage, then payment, then return format. No fluff. Highly efficient.

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

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

Covers purpose, when to use, payment, and return array structure despite no output schema. Adequate for the tool's simplicity.

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

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

Schema coverage is 100%, so baseline is 3. Description adds context by describing output fields and hinting at how parameters (origin/destination) are used, earning 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?

Description clearly states 'Get inland haulage rates' with specific verb and resource, and differentiates from siblings by mentioning route discovery and comparison tools.

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

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

Explicitly states when to use ('when you know the specific origin port and destination'), and directs to shippingrates_inland_search for route discovery and shippingrates_inland_compare for carrier comparison.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds payment requirement ($0.03/call) and return behavior on non-payment (402 with instructions). Also describes return format. No contradiction.

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

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

Concise and well-structured: purpose first, then usage example, then alternative tools, then payment info, then return format. No unnecessary words.

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

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

Despite no output schema, description includes return structure (array of objects). Covers payment, error handling, and typical use case. Complete for a search tool with 4 parameters.

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 parameters with descriptions. Description provides an example usage for keyword but does not add significant meaning beyond 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?

Description clearly states the tool searches for inland transport routes from port to inland destinations for a specific carrier, with an example. It distinguishes from siblings by naming alternative tools for rates and comparison.

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

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

Explicitly says when to use ('discover what haulage routes a carrier offers') and when not to ('For actual haulage rate quotes, use shippingrates_inland_haulage; for comparison, use shippingrates_inland_compare').

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds value by noting it is free, no payment required, and detailing the return structure. No contradictions.

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

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

Every sentence is purposeful: main action, usage guidance, cost, return format, related tools. Front-loaded and no unnecessary words.

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

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

For a list tool with no inputs and good annotations, the description fully covers purpose, usage, cost, and return structure. No gaps.

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

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

No parameters exist, so baseline is 4. The description provides sufficient context about the tool's behavior without needing parameter details.

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 lists all shipping lines with per-country record counts, using specific verb and resource. It distinguishes from siblings by framing it as a discovery tool before querying specific tools.

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

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

Explicitly states when to use (to discover carriers/countries before querying specific tools) and provides alternatives (shippingrates_stats for aggregates, shippingrates_search for keyword discovery).

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

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

Annotations declare readOnlyHint and idempotentHint, which are consistent. The description adds valuable behavioral context: the tool requires a paid call ($0.05 via x402) and returns a 402 error without payment. It also describes the return format, giving the agent a clear picture of the output.

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 at ~100 words, with a front-loaded first sentence defining purpose. It then provides usage guidance, payment info, and return format in a clear, structured manner. No redundant sentences.

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

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

Given the tool's complexity (4 params, no output schema, paid usage), the description covers all necessary aspects: purpose, when to use, payment, and return format. It references sibling tools for alternative flows, aiding contextual understanding. The annotations already cover safety, so description complements well.

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 having a clear description. The tool description does not add extra parameter-level semantics beyond what the schema already provides. Therefore, the baseline score 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 'Get local charges at a port for a specific carrier', clearly stating the action and resource. It lists example charges (THC, documentation fees) and distinguishes itself by referencing sibling tools for when to use this vs others.

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 when calculating total shipping costs at origin or destination' and provides specific alternatives: 'Combine with shippingrates_dd_calculate for a complete port cost picture, or use shippingrates_total_cost for an all-in-one landed cost estimate.' Additionally, it notes the payment requirement and cost.

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

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

Annotations indicate read-only, idempotent, non-destructive. Description adds critical behavioral info: payment requirement ($0.01/call via x402) and error behavior (402 with payment instructions), which goes 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?

Five concise sentences, front-loaded with purpose. Each sentence adds value: purpose, usage alternative, payment info, error behavior, return fields. No redundancy.

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

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

Covers all necessary aspects: purpose, when to use alternative, payment model, error case, and return fields. No output schema, so description compensates by listing return fields.

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

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

Schema has full coverage (100%) and descriptions for both parameters. The description reinforces the 'code' parameter's purpose but adds no new constraints or format details beyond 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 clearly states the tool looks up port details by UN/LOCODE, listing the return fields. It distinguishes from siblings by directing users to shippingrates_search if the code is unknown.

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

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

Explicitly states use cases: validate port codes or get metadata. Provides alternative tool (shippingrates_search) for when UN/LOCODE is unknown, giving clear when-to-use guidance.

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

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

Discloses payment requirement ($0.03/call via x402, returns 402 without payment) and return behavior (current spot rates, contract rate indicators, trend data). Annotations already indicate read-only and idempotent, so description adds behavioral context without 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?

Three paragraphs each serve a distinct purpose (what it does, usage guidance, payment/return). Front-loaded with main action. No wasted sentences; return format is concisely described as an array of fields.

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

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

Given 4 parameters, no output schema, and moderate complexity, the description covers tool purpose, usage, payment, and return fields. Annotations handle safety, so description is complete for effective invocation.

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

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

Schema description coverage is 100% with detailed parameter descriptions (e.g., UN/LOCODE examples). The tool description does not add additional meaning beyond reinforcing the optional container_type filter, so baseline score 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 starts with a clear verb (Get) and resource (ocean freight rates) with scope (between two ports, optional container type filter). It distinguishes from siblings by noting comparison of base freight costs and referencing shippingrates_total_cost for a fuller picture.

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 when-to-use: 'Use this to compare base freight costs across carriers for a specific trade lane.' Also gives alternative: 'For a complete cost picture including surcharges and local charges, use shippingrates_total_cost instead.'

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

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

Annotations indicate readOnlyHint and idempotentHint. The description adds significant behavioral context: it is a paid API ($0.01/call on specific payment networks), returns a 402 payment error if unpaid, and discloses the exact return format (array of objects with specified fields). No contradictions with annotations.

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

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

The description is concise: one sentence for purpose, one for usage, one for payment, one for return format. It is front-loaded with the primary action. Every sentence adds value.

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

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

Given 3 parameters with full schema coverage, no output schema but return format described, and annotations covering safety, the description provides enough context to use the tool effectively. It explains the paid nature, payment failure behavior, and expected output structure.

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 reinforces the ISO 2-letter country code and the limit default/max/min, but does not add new meaning beyond the schema's parameter descriptions. The payment header parameter is mentioned but not further explained.

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 retrieves shipping regulatory updates for a specific country, listing specific categories (customs, documentation, trade restrictions, policy changes). It distinguishes from sibling tools focused on rates, tariffs, congestion, etc.

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

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

The description explicitly says to use it 'to stay current on regulatory changes that may affect shipments to/from a country.' It also notes the payment requirement. However, it does not provide explicit guidance on when not to use it or alternatives among 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 provide readOnly, idempotent, and destructive hints. Description adds critical payment requirement ($0.02/call via x402) and the 402 error condition, going beyond annotations without 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?

Description is concise but includes payment info and return format. Could be slightly tighter, but well-structured with key details 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?

Tool is simple with 3 params and no output schema. Description covers return fields and payment requirement. Lacks error handling beyond payment, but adequate for the 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%, so baseline is 3. Description adds only an example for trade_lane, not significantly adding meaning 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 the tool retrieves schedule reliability metrics for a carrier, specifying on-time performance, average delay, and sample size. It distinguishes from sibling tools by focusing on reliability metrics.

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

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

Explicitly states 'Use this for carrier selection and benchmarking' and defines on-time as ±1 day ETA. While it lacks explicit alternatives, the context and sibling names make it clear.

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

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

Annotations declare readOnlyHint=true and idempotentHint=true, indicating safe, idempotent read operation. The description discloses payment requirement ($0.10/call) and that unpaid calls return 402 with payment instructions. It also details the return structure, adding value beyond annotations.

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

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

The description is concise and well-structured, with the main purpose in the first sentence. It includes essential details like payment and return format without unnecessary verbosity. A minor improvement could be tighter 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?

The tool has no output schema, but the description provides the full return shape. It covers input constraints (UN/LOCODE format implied), payment mechanism, and alternative tools. For a tool of this complexity, the description is complete and actionable.

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% (all 3 parameters have descriptions in the input schema, including examples for origin and destination). The description does not add additional semantic meaning beyond what is already in 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 purpose: 'Get a composite risk score (0-100) for a shipping route' and lists specific factors (port congestion, disruption news, chokepoint impact). It also distinguishes from siblings like shippingrates_congestion and shippingrates_congestion_news.

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

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

Explicitly says 'Use this for route risk screening' and provides a threshold ('scores above 70 indicate elevated risk'). It also directs users to sibling tools for detailed congestion metrics or news, offering 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, openWorldHint, idempotentHint, and destructiveHint as false. The description adds value by stating 'FREE — no payment required' and describing the return structure. While it doesn't cover rate limits or other nuances, it provides sufficient behavioral context alongside 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 concise with four sentences, each serving a distinct purpose: action + scope, usage guidance with examples, cost note, and return structure. No extraneous content, and key information is front-loaded.

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

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

Given the simple input schema (one string parameter), comprehensive annotations, and clear return structure described, the description leaves no significant gaps. It fully equips the agent to invoke the tool correctly even without an output schema.

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

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

The single parameter 'keyword' has full schema coverage, and the description elaborates that it matches against carrier names, port names, country names, and charge types. This adds significant semantic meaning beyond the schema description, enabling effective agent selection.

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 the ShippingRates database by keyword, matching against carrier, port, country, and charge type names. It provides concrete examples (e.g., 'mumbai', 'hapag') and distinguishes from sibling tools like shippingrates_port and shippingrates_lines.

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

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

Explicitly states 'Use this for exploratory queries when you don't know exact codes' and lists related tools with specific use cases (structured port lookup, full carrier listing), offering clear guidance on when to use this tool versus alternatives.

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

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

Annotations already declare readOnlyHint and idempotentHint, so safety is covered. Description adds return field context but no new behavioral traits beyond annotations.

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

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

Three well-structured sentences: purpose, elaboration with usage context, and return fields list. No redundant words.

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

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

Fully complete for a zero-parameter tool with annotations covering safety. Describes purpose, usage, and return format adequately.

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

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

No parameters, so baseline 4. Description does not need to explain parameters.

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

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

Clear verb 'Get current statistics' with specific resource 'ShippingRates database'. Lists included data categories and distinguishes from sibling tools by positioning it as a starting point.

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

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

Explicit guidance: 'Use this as a starting point to understand what data is available before calling other tools.' Also mentions 'FREE — no payment required' and lists related tools with their specific purposes.

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 (readOnlyHint=true, etc.), the description adds critical context: payment triggers ('PAID: $0.02/call...'), error behavior ('returns 402 with payment instructions'), and return format (array with fields). 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 efficiently structured in three clear paragraphs: tool function, usage guidance, and payment/return details. Every sentence adds value without redundancy.

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

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

Given no output schema, the description fully compensates by declaring the exact return structure. It also covers payment, error responses, and relationship to base rates, making the tool self-contained.

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

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

With 100% schema coverage, the baseline is 3. The description does not add extra parameter-level details beyond what the schema already provides, but it implicitly maps parameters to usage context ('carrier in a specific country/direction').

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

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

The description clearly states 'Get carrier-specific surcharges' and lists examples (BAF, CAF, etc.), defining the verb and resource precisely. It also distinguishes from sibling 'shippingrates_total_cost' by noting that this tool returns surcharges individually.

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

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

The description explicitly states when to use ('understand surcharge exposure for a carrier in a specific country/direction') and directs to an alternative ('For a complete cost breakdown, use shippingrates_total_cost'). It also documents payment requirements.

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

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

Discloses that the tool is paid ($0.15/call via x402) and returns 402 on non-payment. Annotations already indicate read-only and idempotent, but the payment info adds crucial behavioral context. 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?

Three focused paragraphs: purpose, usage guidance, and payment/return info. No fluff, each sentence adds value.

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

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

Given no output schema, the description provides a detailed return structure. It also explains payment failure behavior. Covers purpose, usage, inputs, outputs, and constraints adequately.

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 descriptions (100% coverage). The description does not add parameter-level details but lists the components in the output, which indirectly relates to inputs. Baseline 3 is appropriate.

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

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

The description clearly states it calculates the full landed cost of shipping a container, combining multiple cost components. It distinguishes itself from sibling tools by explicitly listing them and noting that a single call replaces 5-6 individual queries.

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

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

Explicitly states when to use this tool ('when the user needs an all-in cost estimate for a specific shipment') and when not to, providing names of dedicated tools for individual components.

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: cost ($0.02/call), behavior without payment (402 response), and return structure (array of objects). No contradictions.

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

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

Four clear sentences: purpose, usage guideline, payment info, return format. No redundancy, front-loaded with key info.

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

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

No output schema, but description specifies return format (array of {carrier, transit_days, ...}). Covers payment, usage, alternative tool. Complete for the 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% with good descriptions for origin and destination (including examples). Description does not add extra parameter semantics beyond what's in schema, 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?

Clearly states verb 'get', resource 'estimated ocean transit times', scope 'between two ports across all carriers'. Distinguishes from sibling shippingrates_transit_schedules by specifying quick comparison vs detailed routing.

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

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

Explicitly says 'Use this for quick transit time comparison' and provides alternative 'For detailed routing... use shippingrates_transit_schedules instead'. Includes payment requirement 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?

Discloses payment cost ($0.03/call via x402) and behavior (returns 402 without payment). Annotations already indicate read-only, idempotent, non-destructive; description adds payment context and response behavior, no contradictions.

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

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

Description is compact (three paragraphs) with front-loaded purpose, followed by usage guidance, payment info, and return format. Every sentence adds value.

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

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

Given no output schema, description explicitly states return structure (array of objects with fields like carrier, service_code, transit_days). Covers payment, filtering purpose, and sibling contrast. Complete for a read-only query tool.

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

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

Schema has 100% coverage with descriptions for all 5 parameters. Description adds no extra parameter-specific meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states 'Get detailed transit schedules for a specific carrier' and lists specific data (service codes, routing via transhipment ports, transit days, sailing frequency). It distinguishes from sibling tool shippingrates_transit by noting it provides more than just transit time.

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

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

Explicitly states 'Use this when you need routing details beyond just transit time' and directs users to shippingrates_transit for quick comparisons. 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 read-only, idempotent, non-destructive. The description adds payment requirement ('PAID: $0.02/call... Without payment, returns 402') and describes the return structure, providing full behavioral context beyond annotations.

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

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

Description is front-loaded with the core purpose and uses only five sentences with no redundant or wasted words. Every sentence serves a clear function: purpose, use case, alternatives, payment info, return format.

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

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

Given the tool's moderate complexity (3 params, no output schema), the description covers all necessary aspects: what it does, when to use, alternatives, payment requirement, and expected return fields. No gaps detected.

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 each parameter (port, x_payment, days_ahead) has detailed descriptions including examples and defaults. The description reinforces the port code format but adds no significant new semantics beyond the schema, so slightly above baseline.

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

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

The description clearly states the verb 'Get' and the resource 'upcoming vessel arrivals and departures at a specific port'. It distinguishes from siblings by naming shippingrates_transit and shippingrates_transit_schedules for related but different 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?

Provides explicit guidance on when to use: 'to check what vessels are expected at a port — useful for booking planning and tracking'. Also specifies when not to use and directs to alternative tools for transit times or detailed routing.

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

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

Discloses payment requirements ($0.03/call, 402 without payment) and data behavior (missing cutoffs remain null, no inference). Annotations indicate readOnly/ idempotent, which align with description; no contradictions.

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

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

Concise and well-structured: purpose first, then usage guidance, data behavior, alternative, payment, and return format. No superfluous sentences.

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

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

Despite no output schema, description provides a clear return structure and covers limitations, payment, and differentiation from sibling, making it complete for a tool with 6 parameters.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by explaining the return structure and the payment parameter, which are not in the input schema, thus enhancing parameter understanding 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 retrieves vessel/voyage schedule options with cutoff deadlines, specifying the resource and distinguishing it from the sibling tool for port-call monitoring without cutoffs.

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

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

Explicitly advises using for booking planning with vessel details and cutoffs, and directs to the sibling tool for port-call monitoring without cutoffs, providing 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.