ShippingRates MCP Server

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

Annotations already indicate readOnlyHint=true and idempotentHint=true. The description adds valuable behavioral context: it's a paid tool ($0.05/call via x402) and that a missing payment results in a 402 status with payment instructions. This goes beyond what annotations provide.

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

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

The description is three sentences plus two short lines for payment and return format. Every sentence is necessary and front-loaded with the core purpose. No redundant or verbose text.

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

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

Given the annotations, full schema coverage, and no output schema, the description covers all needed context: what the tool returns, payment requirements, and behavior on missing payment. The agent has enough information to use 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 schema already documents all four parameters adequately. The description does not add new parameter-level details but provides overall context (LCL, port warehouses). 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 starts with a clear verb ('Get') and specific resource ('CFS handling tariffs'), immediately distinguishing it from sibling tools like inland haulage or surcharges. It explicitly states it's for LCL shipments only.

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 clear use case ('Use this for LCL shipments to estimate warehouse handling costs') and an exclusion ('Not relevant for FCL'), which helps agents decide when to invoke it. However, it does not list any alternative sibling 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 indicate read-only, idempotent, and non-destructive behavior. The description adds critical behavioral info: the tool requires payment ($0.02/call via x402) and returns a 402 error without payment. It also describes the return structure, providing complete transparency 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 four focused sentences: purpose, usage guidance, payment requirement, and return format. Each sentence is necessary and front-loaded, with no extraneous text. This is an ideal length for quick comprehension.

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 parameters, no output schema), the description covers all essential aspects: functionality, usage context, payment details, error behavior, and return fields. No gaps are evident; the tool is fully understandable.

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 well-documented in the input schema (100% coverage), so the description adds minimal parameter-level detail. The description's mention of 'port' and 'metrics' reinforces purpose but does not enhance parameter semantics beyond what the schema already 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 retrieves port congestion metrics (vessel waiting times, berth occupancy, delay trends) for a specific port. It distinguishes itself from the sibling tool shippingrates_congestion_news by explicitly noting that the sibling is for disruption news, not metrics.

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

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

The description provides explicit guidance: use this tool to assess port efficiency and anticipate detention risk, with context on congestion impacts. It also states when not to use it (for news) and names the alternative tool (shippingrates_congestion_news), offering 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by disclosing the paid nature ($0.02/call via x402) and the 402 response without payment. It also describes the return format. While it does not mention rate limits or update frequency, the added context is sufficient 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: purpose, examples, usage guidance, pricing, and return format. Every sentence contributes value. It is not overly verbose, though it could be slightly shortened. Overall, it is concise and well-organized.

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

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

Given 5 parameters, no output schema, and good annotations, the description is complete. It covers the return format, payment requirements, and typical use cases. There are no obvious gaps for a news lookup tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds the default value for days_back (7) which is not in the schema, but otherwise does not deepen meaning beyond the schema's parameter descriptions. The payment parameter is explained in the pricing note. This meets the baseline for parameter semantics.

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

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

The description clearly states 'Get shipping disruption news aggregated from 7 trade press sources — with port tagging and severity classification.' It lists specific topics (Hormuz Strait, Red Sea/Houthi, etc.) and distinguishes from siblings by specifying that this tool provides news while shippingrates_congestion offers quantitative metrics and shippingrates_risk_score provides route-level risk scoring.

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

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

The description explicitly states when to use this tool ('for situational awareness — answers 'are there any active disruptions affecting my route?'') and what to use instead for other needs ('For quantitative port congestion metrics... use shippingrates_congestion instead. For route-level risk scoring, use shippingrates_risk_score'). This provides clear 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.10/call via x402) and error handling (returns 402 without payment), adding crucial context beyond annotations that only indicate read-only, idempotent, non-destructive 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?

Four sentences plus a return format line, front-loaded with purpose, then usage guidance, payment info, and return structure. 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?

Covers purpose, usage, payment, and return format. Minor gap: no mention of integer constraint for days, but schema already includes min/max. Overall sufficient for a calculation 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% and descriptions are adequate. The tool description does not add new semantic information beyond what the schema provides; baseline score of 3 applies.

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

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

The description clearly states 'Calculate demurrage and detention (D&D) costs for one carrier in one country' and specifies it returns free days, per-diem rates, and total cost, distinguishing it from the sibling tool shippingrates_dd_compare.

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: 'when the user needs a detailed cost breakdown for a specific carrier' and provides an alternative: 'To compare D&D costs across all carriers at once, use shippingrates_dd_compare instead.'

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral context: the payment requirement ($0.25/call via x402) and the 402 error response if unpaid. This exceeds basic annotation coverage without contradicting it.

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 purpose, second sentence explains usage context, third sentence directs to the sibling tool, fourth sentence covers payment, and fifth sentence describes the return format. Every sentence earns its place with no redundancy.

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

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

Given the tool's complexity (cross-carrier comparison, payment gating) and the absence of an output schema, the description provides sufficient context: purpose, usage, sibling distinction, payment model, error condition, and return format. No critical information 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?

Schema coverage is 100%, so the input schema already describes all parameters with meaningful descriptions. The description does not add new semantic detail for parameters, but it confirms the input dimensions (country, container type, days) in context. 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 compares demurrage and detention costs across all carriers for a given country, container type, and detention days. It uses specific verbs ('Compare') and resources ('demurrage and detention costs across ALL available carriers'), and distinguishes itself from the sibling tool 'shippingrates_dd_calculate'.

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

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

Explicitly states when to use the tool: 'Use this for freight procurement and carrier selection.' It also provides a clear alternative: 'For a single carrier's detailed D&D breakdown, use shippingrates_dd_calculate instead.' This meets the highest standard of 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. Description adds behavioral details: payment model ($0.02/call via x402) and return of 402 without payment. 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 paragraphs with clear sections: tool purpose, usage/payment, return format. Concise with no wasted words, though could be more 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?

Given 5 parameters, no output schema, and payment complexity, the description covers all essential aspects: purpose, filters, payment model, return fields, and sibling tool reference.

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

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

Schema description coverage is 100%, so baseline is 3. Description does not add extra meaning to parameters beyond what schema provides; it only describes output fields and usage context.

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

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

The description clearly states it searches India's ICD/CFS directory with GPS coordinates, rail connectivity, etc. It distinguishes from sibling tool shippingrates_inland_haulage by noting combined use for inland logistics planning.

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: finding facilities near inland destinations or checking rail connectivity. Mentions payment requirement. No explicit when-not-to-use, but 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 'Rates are updated daily' and 'FREE — no payment required' beyond annotations that already indicate read-only, idempotent, non-destructive 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?

Three concise sentences plus return format, front-loaded with purpose, no extraneous text.

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

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

Fully describes behavior, return format, update frequency, and cost; no gaps given simple tool and rich annotations.

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

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

Schema coverage is 100% with descriptions; description adds examples and context (list of currencies), slightly more than baseline 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?

States 'Get current exchange rate between two currencies' with specific currencies listed, clearly distinct from sibling 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 says 'useful for converting shipping costs' and 'normalize costs from different carriers/countries', providing clear context for use, though no explicit 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 provide readOnlyHint, idempotentHint, destructiveHint. The description adds valuable behavioral traits: it is a paid call ($0.08/call), returns 402 if unpaid, and returns a sorted array with specific 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?

Concise, well-structured text with three short paragraphs. The main action is front-loaded, followed by usage guidance and payment details. 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?

Despite no output schema, the description details the return format including fields and sorting. It also covers payment requirements, making the tool's behavior fully understandable.

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 individual parameter descriptions. The description does not add new semantic meaning beyond the schema for the parameters. 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 compares inland haulage rates across all carriers for a port-to-ICD/city pair, sorted cheapest first. It distinguishes from sibling tools by naming alternatives for single carrier rates (inland_haulage) and route discovery (inland_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?

Explicitly states when to use this tool (carrier selection on inland legs) and when not to (single carrier rates - use inland_haulage), and suggests a prerequisite step (use inland_search first).

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 that it is a paid call ($0.05) and returns 402 if no payment, which is critical extra behavioral info. Also describes return format.

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: four sentences covering action, usage context, payment, and return format. Every sentence adds value and 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?

Despite no output schema, the description explicitly lists return fields. Covers payment, alternatives, and required inputs. Complete for an agent to decide and 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% with detailed parameter descriptions. The description does not add additional meaning beyond the schema; it only restates the general purpose. 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 the tool retrieves inland haulage rates between a port and inland location, with specific verbs and resource. Distinguishes from sibling tools by explicitly mentioning 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?

Explicitly says when to use (when origin port and destination are known) and provides alternatives: use shippingrates_inland_search to discover routes and shippingrates_inland_compare to compare rates. Also notes payment requirement.

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

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

Annotations provide readOnlyHint, idempotentHint, etc. Description adds critical behavioral info: payment requirement ($0.03/call via x402) and the 402 response without payment, plus output structure. No contradiction.

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

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

Concise: first sentence states purpose, then usage guidance, payment, and returns. Each sentence adds value without redundancy. Well-structured for easy scanning.

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 lists expected return fields (origin, destination, mode, etc.). Covers purpose, usage, payment, and response adequately. No gaps for this moderately complex tool.

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

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

Schema coverage is 100%, so baseline 3. Description provides a usage example for 'keyword' but does not add substantial new meaning beyond the schema's already clear descriptions. Scores meet 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 'Search' and resource 'inland transport routes', specifying scope 'from port to inland destinations for a specific carrier'. It distinguishes itself by naming sibling tools for different use cases (rates, 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 tells when to use this tool ('discover what haulage routes a carrier offers') and when not to, with direct alternatives: 'For actual haulage rate quotes, use shippingrates_inland_haulage. For cross-carrier rate 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 indicate readOnly, idempotent, non-destructive. Description adds that it is free and describes the return format (Array of objects). No contradictions.

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

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

Extremely concise: two short paragraphs and a 'Returns' line plus related tools. Every sentence is informative with no redundancy.

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

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

Handles all aspects: purpose, usage, return structure, free indication. No output schema, but description explains the return format completely.

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

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

Input schema has zero parameters, so baseline is 4. Description correctly adds no parameter information as none are needed.

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 'List all shipping lines' with specific verb and resource, and adds scope 'with per-country record counts'. Distinguishes from siblings by mentioning related 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 says 'Use this to discover which carriers and countries have data before querying specific tools.' Provides guidance on when to use and lists alternatives (shippingrates_stats, shippingrates_search). Also notes it is free.

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 and idempotent. Description adds payment details ($0.05/call via x402) and return format, enhancing transparency 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 four sentences covering purpose, usage, payment, and return format. Efficient and well-structured, though slightly wordy.

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?

Provides return format, payment requirement, and sibling tool context. Without output schema, it adequately covers needed information for agent invocation.

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

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

Schema description coverage is 100%, so baseline is 3. Description adds limited extra meaning beyond schema property descriptions, but provides context for 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 clearly states the tool retrieves local charges at a port for a specific carrier, listing specific charge types and differentiating from sibling tools like shippingrates_dd_calculate and shippingrates_total_cost.

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

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

Explicitly states when to use ('when calculating total shipping costs at origin or destination') and provides alternative tools for different scenarios, offering clear guidance for the agent.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive. Description adds significant behavioral context: payment requirement ($0.01/call), method of payment (x402 via USDC on Base or Solana), and the 402 error response when payment is missing. 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?

Three concise sentences cover purpose, usage, payment, and return fields. Front-loaded with main action. No wasted words; every sentence adds essential information.

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

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

Given the simple schema and no output schema, the description fully covers what the tool returns (fields list), prerequisites (UN/LOCODE), payment requirements, and error behavior. No gaps remain for this simple lookup 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% for both parameters. The description adds minor value (UN/LOCODE examples like 'INNSA'), but the schema already adequately defines the parameters. 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?

Description clearly states 'Look up port details by UN/LOCODE' with specific resource (port details) and method (look up by code). It distinguishes itself from sibling shippingrates_search by explicitly advising to use that tool when the UN/LOCODE 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 when to use (validate port codes, get metadata) and when not to (if UN/LOCODE unknown), with a clear alternative (use shippingrates_search). Also includes payment instructions. This is exemplary 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, with 402 returned if unpaid) and describes return format including trend data, adding value beyond annotations which already indicate read-only and idempotent 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?

Very concise: three sentences plus a payment note and return type, each sentence earning its place. Front-loaded with core purpose, 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?

Provides complete context: explains return format (array of fields) since no output schema exists, mentions payment behavior, references a sibling for total cost, and covers all key aspects for agent selection and invocation.

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

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

Schema description coverage is 100%, so baseline is 3. The description reinforces parameter purposes (port codes, container type filter) but does not add significant new meaning beyond the schema's existing parameter descriptions.

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

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

The description clearly states it gets ocean freight rates between two ports, specifies optional container type filter, and distinguishes from the sibling 'shippingrates_total_cost' by noting that this tool is for base freight costs only.

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

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

Explicitly states when to use (compare base freight costs across carriers for a specific trade lane) and when to use an alternative (use shippingrates_total_cost for complete cost picture including surcharges and local charges).

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds important behavioral details: payment requirement ($0.01/call), behavior without payment (returns 402 with payment instructions), and the return structure (Array of objects with specific fields). No contradiction.

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

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

The description is concise and well-structured. It starts with the primary purpose, then provides usage context, payment information, and return format in a clear, front-loaded manner. 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 the tool's complexity (3 parameters, no nested objects, good annotations, no output schema), the description is complete. It explains what the tool returns (Array of objects with fields), when to use it, and the payment requirement. 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?

Schema coverage is 100%, with all three parameters described in the schema. The description does not add new parameter details beyond the schema, so 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 clearly states the tool's purpose: 'Get recent shipping regulatory updates and compliance requirements for a specific country.' It lists specific aspects like customs regulations, documentation requirements, trade restrictions, and policy changes, which distinguishes it from sibling tools focused on 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 includes usage guidance: 'Use this to stay current on regulatory changes that may affect shipments to/from a country.' While it implies when to use, it does not explicitly state when not to use or provide direct alternatives among the many sibling tools.

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

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

Annotations declare readOnlyHint, idempotentHint, and no destructive effect. The description adds critical behavioral context: payment required ($0.02/call via x402), returns 402 without payment, defines on-time as ±1 day (industry standard), and lists return fields. This exceeds annotation coverage and provides full transparency.

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 four sentences, each serving a purpose: stating functionality, use case, definition/payment, and return fields. It is well-structured and front-loaded with the main action.

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

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

Despite no output schema, the description lists all return fields explicitly, covering essential metrics. It also mentions payment prerequisite. For a simple query tool with 3 parameters and clear annotations, the description is fully complete and leaves no critical 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?

Schema coverage is 100%, so description carries minimal burden. The description mentions trade_lane as a filter but does not add examples or format details beyond what the schema provides. Baseline 3 is appropriate as no extra semantic value is added.

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

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

The description clearly states the tool retrieves schedule reliability metrics for a carrier, including on-time percentage, avg delay, and sample size. It specifies the verb 'Get' and resource 'carrier reliability metrics', distinguishing it from sibling tools like shippingrates_risk_score or shippingrates_stats, which focus on different aspects.

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 use case: 'Use this for carrier selection and benchmarking — answers "how reliable is this carrier on this trade lane?"'. It provides clear context but does not offer explicit when-not-to-use or alternative tool suggestions, which is a minor gap given the large sibling set.

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 behavioral context beyond annotations: payment requirement ($0.10/call via x402), behavior without payment (returns 402), and the return structure. This fully compensates for the lack of output schema.

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

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

The description is efficient: first sentence states purpose, then components, usage guidance, alternatives, payment info, and return fields. 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?

For a risk score tool, the description covers purpose, factors, interpretation, payment, and return fields. A minor gap is not detailing all chokepoints or factor weights, but sufficient for agent decision-making.

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

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

Schema coverage is 100% with detailed descriptions of origin/destination parameters. The description adds value by explaining the payment parameter context and the overall payment flow.

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 the components (port congestion, disruption news, chokepoint impact). It distinguishes itself from sibling tools by naming alternatives 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 when to use ('for route risk screening') and provides interpretation guidance ('Scores above 70 indicate elevated risk'). It also gives clear alternatives for detailed metrics.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: 'FREE — no payment required' and specifies the return structure: 'Returns: { trade_lanes: [...], local_charges: [...], lines: [...] } matching the keyword.' 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 three sentences plus a return format line, all front-loaded with the core purpose. Every sentence adds value: purpose, usage examples, cost, return structure, and sibling differentiation. 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?

With no output schema, the description provides the full return structure. It covers purpose, usage guidance, parameter semantics, cost, and related tools. For a simple search tool with one parameter, the description is complete and sufficient 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?

Only one parameter 'keyword' with 100% schema coverage. The description adds meaning beyond the schema by stating that matches occur against 'carrier names, port names, country names, and charge types'. The schema already provides examples, so the description adds some semantic value, justifying a 4.

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

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

The description clearly states 'Search the ShippingRates database by keyword' with specific matching fields (carrier names, port names, etc.). It distinguishes from siblings by mentioning related tools: 'Use shippingrates_port for structured port lookup by UN/LOCODE, shippingrates_lines for full carrier listing.'

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

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

The description explicitly says 'Use this for exploratory queries when you don't know exact codes' and provides examples like 'search "mumbai" to find port codes' or '"hapag" to find Hapag-Lloyd data coverage'. It also mentions 'FREE — no payment required' and directly references alternative tools for structured lookups.

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

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

Annotations already provide readOnlyHint, idempotentHint. Description adds value by disclosing it is free, and detailing the structure of the return value (record counts, last scrape 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?

Description is reasonably concise with front-loaded purpose. Lists return fields and related tools. Could be slightly tighter, but no significant 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 zero parameters and no output schema, the description sufficiently describes what the tool returns and its role as a starting point. Contextually complete for a statistics tool.

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

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

Input schema has zero parameters, so baseline is 4. Description does not need to add parameter info; it correctly focuses on the overall purpose and return data.

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

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

The description clearly states the tool retrieves current statistics for the ShippingRates database, using specific verb 'Get' and resource 'statistics'. It distinguishes itself from siblings by naming related tools for different purposes.

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

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

Explicitly advises using this tool as a starting point to understand available data before other tools, and lists related tools (shippingrates_lines, shippingrates_search) for further breakdowns.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. Description adds value by disclosing payment requirement ($0.02/call, 402 response without payment) and return format (array of objects with field names). 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?

Five sentences, each serving a distinct purpose: tool action, usage context, billing info, return structure. Front-loaded with purpose. No redundant or vague 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?

No output schema, but description details the return structure. Parameter count (4) and siblings (24) are handled with clear usage guidance. Missing explicit mention of x_payment header usage context, but overall sufficient.

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

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

Schema coverage is 100% with clear descriptions for all 4 parameters. Description adds context by linking surcharges to carrier/line but does not detail each parameter 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?

Description opens with a clear verb-object phrase: 'Get carrier-specific surcharges' followed by explicit examples (BAF, CAF, PSS, EBS). It distinguishes itself by focusing on surcharge exposure vs. full cost breakdown, effectively differentiating from sibling shippingrates_total_cost.

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

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

Explicitly states when to use: 'understand surcharge exposure for a carrier in a specific country/direction' and when not: 'For a complete cost breakdown, use shippingrates_total_cost which includes surcharges automatically.' Directs to an alternative sibling.

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

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

Discloses payment requirement ($0.15/call, x402), failure mode (402 response), and return structure. Annotations already indicate read-only and idempotent, and the description adds valuable behavioral context beyond annotations.

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

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

Concise and well-structured: main purpose first, then usage guidelines, payment info, and return format. Every sentence adds value with no redundancy.

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

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

Given no output schema, description fully specifies the return shape. Parameters are fully documented in schema. Usage context and alternatives are clear. Covers all necessary information for an agent to use the tool correctly.

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

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

Input schema has 100% coverage with detailed descriptions. The description does not add extra meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool calculates full landed cost for a container, specifying it combines freight rates, surcharges, local charges, detention, and transit time. It distinguishes itself from siblings by noting it replaces 5-6 individual queries.

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

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

Explicitly tells when to use (all-in cost estimate) and directs to dedicated tools for individual components, naming specific sibling 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=true, idempotentHint=true, destructiveHint=false, so safety profile is clear. Description adds valuable behavioral context: payment requirement ($0.02/call via x402), return format (Array of objects with specific fields), and that without payment it returns 402. This 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?

Description is concise (4 sentences), front-loaded with purpose, then usage, then alternative, then payment, then return format. Every sentence adds value with no redundancy.

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

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

Given the tool's simplicity (2 required params, no output schema), the description fully covers purpose, usage, payment, and return format. An agent can correctly select and invoke this tool without additional information.

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

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

Schema description coverage is 100% (3 parameters fully documented). The description provides UN/LOCODE examples for origin and destination but does not add meaning beyond the schema. Baseline is 3; moderate extra value from contextual examples.

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 'Get estimated ocean transit times between two ports across all available carriers.' The verb 'get' and resource 'estimated ocean transit times' are specific. It distinguishes from sibling tool 'shippingrates_transit_schedules' by noting it provides 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 guides when to use this tool: 'Use this for quick transit time comparison between ports' and when not to: 'For detailed routing...use shippingrates_transit_schedules instead.' This provides clear differentiation and 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 indicate readOnlyHint=true and idempotentHint=true. The description adds significant behavioral context: the tool is paid, returns 402 without payment, and describes the return format in detail. This goes beyond annotations, though it doesn't cover rate limits or other restrictions.

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

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

The description is concise (6 sentences) and well-structured: action first, then usage guidance, payment info, and return format. Every sentence adds value with no redundancy.

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

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

Given 5 parameters, no output schema, and moderate complexity, the description covers the core functionality, return format, and payment details. It could briefly mention pagination or data limits, but overall it is fairly complete for a read-only, idempotent 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 does not elaborate on individual parameters beyond the schema, but it provides overall context that helps understand parameter usage. No additional parameter-specific details are given.

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 detailed transit schedules for a specific carrier, listing specific fields like service codes, transhipment ports, and frequency. It also distinguishes itself from sibling tool shippingrates_transit by stating that the latter is for quick transit time comparison.

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

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

The description explicitly says when to use this tool ('when you need routing details beyond just transit time') and when not ('for quick transit time comparison, use shippingrates_transit'). It also provides payment instructions and error behavior, giving clear usage context.

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

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

Annotations already indicate read-only and idempotent. Description adds payment behavior (returns 402 if unpaid) and returns structure, but no new behavioral traits beyond what annotations imply.

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?

Front-loaded with purpose, then usage, return fields, alternatives, and payment. Each sentence serves a purpose, though slightly long; well-organized.

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

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

No output schema, but description details return fields. Mentions payment and default days_ahead (implied). Adequate for a simple list tool, though explicit default mention would help.

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

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

Schema covers 100% of parameters with good descriptions and examples. Description reinforces but doesn't add new meaning 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 it fetches upcoming vessel arrivals and departures at a specific port, and explicitly distinguishes from sibling tools shippingrates_transit and shippingrates_transit_schedules.

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

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

Provides explicit when-to-use context (checking vessels for booking planning) and when-not-to-use with specific alternative tool names, including transit time and detailed routing 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 indicate safe read operation. Description adds critical behavior: missing cutoffs are null/absent (not inferred), payment requirement ($0.03/call via x402) and 402 response without payment. 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. Front-loaded with main action, then usage guidance, behavior notes, payment info, and return structure. Every sentence is valuable with no redundancy.

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

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

Despite no output schema, description includes a return structure outline. Covers purpose, usage, cutoff behavior, payment, and alternative tool. Sufficient for an AI agent to understand the tool's complete 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?

Schema coverage is 100% with good parameter descriptions. The description adds some context (e.g., missing cutoffs remain null) but does not significantly enhance parameter understanding 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 it retrieves vessel schedules with cutoffs, and explicitly distinguishes from sibling shippingrates_vessel_schedule which lacks cutoff details. Verb 'get' and resource 'vessel/voyage schedule options' are specific.

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

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

Explicitly says when to use (booking planning needing cutoffs) and when not (port-call monitoring without cutoffs), naming the alternative tool. This is perfect guidance.

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