Predictive port congestion signals for global trade, supply chain and quantitative finance.
Scored across 3 tools
The three tools have clearly distinct purposes: single-port risk lookup, batch risk lookup, and supported-port discovery. The batch endpoint is a convenience wrapper but is explicitly described as the parallel version, so an agent should not misselect.
Tool names follow a consistent snake_case verb_noun pattern: get_ for lookups and list_ for enumeration. Singular versus plural in get_port_risk and get_ports_risk is a sensible convention for single vs batch operations.
Three tools is an appropriately compact surface for a read-only port congestion oracle with a fixed set of 15 supported ports. Each tool earns its place: discovery, single query, and batch query.
For the stated domain, the tool surface is complete: list_supported_ports provides the available universe, get_port_risk covers individual lookups, and get_ports_risk enables efficient multi-port queries. No write or lifecycle operations are expected for this predictive read-only service.
Return the predictive congestion signal for a single port.
Args:
port_id: UN/LOCODE of the port, e.g. "BRSSZ" (Santos), "CNSHA" (Shanghai).
| Name | Required | Description | Default |
|---|---|---|---|
| port_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It implies a read-only query by saying 'Return', but it does not disclose behavior for invalid or unsupported ports, error handling, or data freshness. For a simple lookup the basic transaction is adequately transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded, with two short sentences plus an args list containing only the necessary parameter explanation. No filler or redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter lookup with an output schema, the description adequately covers the input format and the purpose of the result. The only missing context is explicit routing to siblings or a note about supported-port preconditions, which is useful but not critical for invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only describes port_id as a string, while the description adds essential semantic detail: it is a UN/LOCODE and provides concrete examples like 'BRSSZ' and 'CNSHA'. This fully compensates for the 0% schema description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Return') and resource ('predictive congestion signal for a single port'), which distinguishes it from the plural sibling get_ports_risk. Concrete UN/LOCODE examples further clarify what the tool operates on.
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?
'For a single port' provides clear context that this tool is for one port, implying the plural sibling would be used for multiple ports. However, it does not explicitly name alternatives or state exclusions such as checking list_supported_ports beforehand.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return congestion signals for several ports in parallel.
Args:
port_ids: list of UN/LOCODEs, e.g. ["BRSSZ", "CNSHA", "NLRTM"].
| Name | Required | Description | Default |
|---|---|---|---|
| port_ids | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full behavioral burden. It does disclose a read-style operation ('Return') and parallel execution, but it does not mention invalid LOCODE handling, rate limits, partial-failure behavior, or explicitly confirm there are no side effects. This is insufficient for 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 compact and front-loaded: the main purpose appears in the first sentence, followed by a single parameter explanation. There is no filler or redundant restating of the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simple shape (one required parameter, no nested objects) and the presence of an output schema covering return values, the description is nearly complete. It clearly documents the parameter format and batch behavior, though explicit guidance about when to use get_port_risk instead would improve it further.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only says port_ids is an array of strings, while the description adds essential meaning: these are UN/LOCODEs, with concrete examples like 'BRSSZ', 'CNSHA', and 'NLRTM'. This covers the sole required parameter well, though it does not address edge cases such as empty lists.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Return congestion signals for several ports in parallel'. This clearly distinguishes it from the singular sibling get_port_risk and from list_supported_ports. An agent can infer the batch lookup intent immediately.
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 phrase 'several ports in parallel' implies the tool is for batch queries, which gives some usage context. However, it never explicitly names get_port_risk as the single-port alternative or provides when-not conditions, so the routing decision is mostly left implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the 15 ports pre-seeded in the oracle (id, name, country).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses the exact fixed count (15), the static 'pre-seeded' nature, and the fields returned, which is transparent for a read-only list. Minor omissions like error conditions are acceptable for a zero-parameter tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with no wasted words. It conveys the action, resource, quantity, and output fields efficiently.
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 parameterless listing tool with an output schema, the description provides everything an agent needs: what is listed, how many items, and their fields. No meaningful invocation context is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The description adds no parameter complexity because none exists, and schema coverage is effectively complete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('List'), a specific resource ('ports pre-seeded in the oracle'), and the returned fields ('id, name, country'). It is immediately distinct from the sibling risk-focused tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no indication of when to use this tool versus get_port_risk or get_ports_risk, nor any exclusions. An agent must infer that this is the simple enumeration tool and that risk data belongs to siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
get_port_riskget_ports_risklist_supported_portsIMF PortWatch MCP — global maritime trade & chokepoint signals (free, no auth)
Pay-per-call shipping evidence: canal queues, tanker flows, container and carbon exceptions.
Ocean & multimodal freight intelligence: rates, landed cost, transit, customs, risk, ship decisions
Signed global shipping & commodity data: oil, LNG, grain, sanctions, fleet, emissions.
Add one secure layer between your agents and this server.
