FreightUtils MCP Server

Incoterms 2020 Lookup

incoterms_lookup

Read-onlyIdempotent

Look up the 11 Incoterms 2020 trade rules — who pays for transport, insurance and customs clearance, and where risk transfers from seller to buyer. 7 rules work for any transport mode (EXW, FCA, CPT, CIP, DAP, DPU, DDP); 4 are sea/inland-waterway only (FAS, FOB, CFR, CIF).

Provide code for one rule, category (any_mode | sea_only) for a filtered list, or neither to list all 11 (a list is summary rows — code, name, category, summary — with full: true for the full rules). Behavior: read-only reference; an unknown code errors with the valid code list, and DAT — replaced in Incoterms 2020 — names its successor, DPU (ICC). Rate-limited: a limit error carries reset_at, the UTC time the allowance resets.

Returns: the rule record — name, category, summary, seller_responsibility, buyer_responsibility, risk_transfer, cost_transfer, insurance, export/import clearance, best_for and watch_out — under result, plus confidence, _source and citation (the FreightUtils v1 response envelope).

Limitations: summarised guidance on ICC Incoterms 2020; the ICC publication is the binding text and specific contract wording prevails.

Related: uk_duty_calculator (accepts an incoterm when composing the CIF value), shipment_summary (composite analysis).

Identifiers: Each record carries fu_id, a stable FreightUtils identifier (and fu_version_id where the dataset has editions); resolve_reference resolves one to exactly its record.

Input Schema

Name	Required	Description
`code`	No	Incoterm code (3 letters, e.g., "FOB", "CIF")
`full`	No	Lists only: true returns full records (provenance, sources, rationale) instead of summary rows. A single-record call always returns the full record.
`limit`	No	Lists only: rows per page (default: every row for summaries; 5 with full: true).
`offset`	No	Lists only: rows to skip (default 0). The response gives total and next_offset.
`category`	No	Filter by mode

Output Schema

Name	Required	Description	Default
`ok`	Yes
`_meta`	No
`as_of`	No
`result`	Yes
`status`	No
`_source`	Yes
`edition`	No
`citation`	Yes
`validity`	No
`warnings`	No
`confidence`	Yes
`missing_inputs`	No
`blocking_errors`	No
`envelope_version`	Yes
`normalized_input`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedNov 6, 2026

addedOutput schema / properties / _meta / properties / upstream

Added value: +{
+  "additionalProperties": {},
+  "properties": {
+    "datasets": {
+      "additionalProperties": {
+        "additionalProperties": {},
+        "properties": {
+          "kind": {
+            "anyOf": [
+              {
+                "enum": [
+                  "watched",
+                  "checksum-only",
+                  "manual"
+                ],
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "last_success": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "reason": {
+            "type": "string"
+          },
+          "stale": {
+            "type": "boolean"
+          },
+          "state": {
+            "enum": [
+              "in_step",
+              "changed_upstream",
+              "schema_drift",
+              "unreachable",
+              "window_missed",
+              "unknown"
+            ],
+            "type": "string"
+          },
+          "window_days": {
+            "type": [
+              "number",
+              "null"
+            ]
+          }
+        },
+        "required": [
+          "state",
+          "kind",
+          "last_success",
+          "window_days",
+          "stale"
+        ],
+        "type": "object"
+      },
+      "propertyNames": {
+        "type": "string"
+      },
+      "type": "object"
+    },
+    "stale": {
+      "type": "boolean"
+    },
+    "state": {
+      "enum": [
+        "in_step",
+        "changed_upstream",
+        "schema_drift",
+        "unreachable",
+        "window_missed",
+        "unknown"
+      ],
+      "type": "string"
+    },
+    "state_read_at": {
+      "type": [
+        "string",
+        "null"
+      ]
+    }
+  },
+  "required": [
+    "state",
+    "stale",
+    "state_read_at",
+    "datasets"
+  ],
+  "type": "object"
+}

Changed1 schema field changedNov 6, 2026

addedOutput schema / properties / _meta / properties / ids

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "pattern": {
+      "type": "string"
+    },
+    "scheme": {
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    }
+  },
+  "required": [
+    "scheme",
+    "pattern"
+  ],
+  "type": "object"
+}

Changed2 schema fields changedNov 4, 2026
- removedOutput schema / properties / _meta / properties / receipt / properties / reason / const
```
Removed value: -"key_required"
```
- addedOutput schema / properties / _meta / properties / receipt / properties / reason / enum
```
Added value: +[
+  "key_required",
+  "quota"
+]
```

Changed1 schema field changedOct 30, 2026

addedOutput schema / properties / _meta / properties / receipt

Added value: +{
+  "additionalProperties": {},
+  "properties": {
+    "created_at": {
+      "type": "string"
+    },
+    "dataset_version": {
+      "additionalProperties": {
+        "type": "string"
+      },
+      "propertyNames": {
+        "type": "string"
+      },
+      "type": "object"
+    },
+    "engine_version": {
+      "type": "string"
+    },
+    "inputs": {},
+    "reason": {
+      "const": "key_required",
+      "type": "string"
+    },
+    "receipt_hash": {
+      "type": "string"
+    },
+    "result": {
+      "additionalProperties": {},
+      "propertyNames": {
+        "type": "string"
+      },
+      "type": "object"
+    },
+    "schema_version": {
+      "type": "string"
+    },
+    "stored": {
+      "const": false,
+      "type": "boolean"
+    },
+    "tool": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "stored",
+    "reason",
+    "schema_version",
+    "receipt_hash",
+    "created_at",
+    "tool",
+    "inputs",
+    "dataset_version",
+    "engine_version",
+    "result"
+  ],
+  "type": "object"
+}

Changed1 schema field changedOct 29, 2026
- addedOutput schema / properties / _meta / properties / edition_basis
```
Added value: +{
+  "type": "string"
+}
```

Changed1 schema field changedOct 29, 2026

addedOutput schema / properties / _meta

Added value: +{
+  "additionalProperties": {},
+  "properties": {
+    "check_id": {
+      "type": "string"
+    },
+    "receipt_url": {
+      "type": "string"
+    }
+  },
+  "type": "object"
+}

Changed5 schema fields changedOct 29, 2026

addedOutput schema / properties / as_of

Added value: +{
+  "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+  "type": "string"
+}

addedOutput schema / properties / edition

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": false,
+      "properties": {
+        "applies_from": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "may_apply_until": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "name": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "name",
+        "applies_from",
+        "may_apply_until"
+      ],
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}

changedOutput schema / properties / envelope_version / enum

Previous value: -[
-  "1",
-  "1.1"
-]New value: +[
+  "1",
+  "1.1",
+  "1.2"
+]

addedOutput schema / properties / missing_inputs

Added value: +{
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedOutput schema / properties / status

Added value: +{
+  "enum": [
+    "ok",
+    "partial",
+    "not_found",
+    "unsupported",
+    "ambiguous"
+  ],
+  "type": "string"
+}

Changed2 schema fields changedOct 28, 2026
- removedOutput schema / properties / validity / properties / effective_to / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / validity / properties / effective_to / type
```
Added value: +[
+  "string",
+  "null"
+]
```
Changed1 schema field changedOct 8, 2026
- addedInput schema / additionalProperties
```
Added value: +false
```

Changed3 schema fields changedOct 8, 2026

addedInput schema / properties / full

Added value: +{
+  "description": "Lists only: true returns full records (provenance, sources, rationale) instead of summary rows. A single-record call always returns the full record.",
+  "type": "boolean"
+}

addedInput schema / properties / limit

Added value: +{
+  "description": "Lists only: rows per page (default: every row for summaries; 5 with full: true).",
+  "maximum": 100,
+  "minimum": 1,
+  "type": "integer"
+}

addedInput schema / properties / offset

Added value: +{
+  "description": "Lists only: rows to skip (default 0). The response gives total and next_offset.",
+  "maximum": 9007199254740991,
+  "minimum": 0,
+  "type": "integer"
+}

Changed5 schema fields changedAug 11, 2026
- addedOutput schema / properties / _source / properties / authority_current_edition
```
Added value: +{
+  "type": "string"
+}
```
- addedOutput schema / properties / _source / properties / checked_at
```
Added value: +{
+  "type": "string"
+}
```
- addedOutput schema / properties / _source / properties / dataset_edition
```
Added value: +{
+  "type": "string"
+}
```
- removedOutput schema / properties / envelope_version / const
```
Removed value: -"1"
```
- addedOutput schema / properties / envelope_version / enum
```
Added value: +[
+  "1",
+  "1.1"
+]
```

Changed1 schema field changedJul 9, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "_source": {
+      "additionalProperties": false,
+      "properties": {
+        "checked": {
+          "type": "string"
+        },
+        "name": {
+          "type": "string"
+        },
+        "provenance_status": {
+          "enum": [
+            "verified",
+            "pending-verification",
+            "computed",
+            "live"
+          ],
+          "type": "string"
+        },
+        "source_url": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "name",
+        "checked",
+        "provenance_status"
+      ],
+      "type": "object"
+    },
+    "blocking_errors": {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "code": {
+            "type": "string"
+          },
+          "message": {
+            "type": "string"
+          },
+          "recovery": {
+            "additionalProperties": false,
+            "properties": {
+              "action": {
+                "type": "string"
+              },
+              "params": {
+                "additionalProperties": {},
+                "propertyNames": {
+                  "type": "string"
+                },
+                "type": "object"
+              },
+              "tool": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "action"
+            ],
+            "type": "object"
+          }
+        },
+        "required": [
+          "code",
+          "message",
+          "recovery"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "citation": {
+      "additionalProperties": false,
+      "properties": {
+        "qualifier": {
+          "type": "string"
+        },
+        "text": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "text"
+      ],
+      "type": "object"
+    },
+    "confidence": {
+      "additionalProperties": false,
+      "properties": {
+        "basis": {
+          "enum": [
+            "deterministic",
+            "provenance",
+            "match_quality",
+            "freshness"
+          ],
+          "type": "string"
+        },
+        "level": {
+          "enum": [
+            "high",
+            "medium",
+            "low"
+          ],
+          "type": "string"
+        },
+        "score": {
+          "maximum": 1,
+          "minimum": 0,
+          "type": "number"
+        }
+      },
+      "required": [
+        "level",
+        "basis"
+      ],
+      "type": "object"
+    },
+    "envelope_version": {
+      "const": "1",
+      "type": "string"
+    },
+    "normalized_input": {
+      "additionalProperties": {},
+      "propertyNames": {
+        "type": "string"
+      },
+      "type": "object"
+    },
+    "ok": {
+      "type": "boolean"
+    },
+    "result": {
+      "additionalProperties": {},
+      "propertyNames": {
+        "type": "string"
+      },
+      "type": "object"
+    },
+    "validity": {
+      "additionalProperties": false,
+      "properties": {
+        "as_of": {
+          "type": "string"
+        },
+        "effective_from": {
+          "type": "string"
+        },
+        "effective_to": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      },
+      "required": [
+        "as_of"
+      ],
+      "type": "object"
+    },
+    "warnings": {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "code": {
+            "type": "string"
+          },
+          "details": {
+            "additionalProperties": {},
+            "propertyNames": {
+              "type": "string"
+            },
+            "type": "object"
+          },
+          "message": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "code",
+          "message"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "envelope_version",
+    "ok",
+    "result",
+    "confidence",
+    "_source",
+    "citation"
+  ],
+  "type": "object"
+}

Changed2 schema fields changedJun 19, 2026

changedInput schema / properties / code / description

Previous value: -"Incoterm code (e.g., \"FOB\", \"CIF\")"New value: +"Incoterm code (3 letters, e.g., \"FOB\", \"CIF\")"

addedInput schema / properties / code / pattern
```
Added value: +"^[A-Za-z]{3}$"
```

First observedApr 23, 2026

TDQS

A4.6/5.0

Behavior4/5

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

Annotations already cover read-only, idempotent, non-destructive and closed-world, and the description still adds real behavioral detail: unknown codes error with the valid code list, DAT resolves to its successor DPU, and rate-limit errors carry reset_at in UTC. What it does not cover is whether a code lookup is case-sensitive or how confidence/_source should be interpreted, so it stops just short of a 5.

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

Conciseness4/5

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

Front-loaded with purpose and scope, then call shapes, then behavior and returns; each block is doing distinct work. It is on the dense side and the trailing 'Identifiers' section is somewhat tangential for a lookup call, but no sentence is pure filler.

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

Completeness5/5

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

For a 5-parameter reference lookup with an output schema and full annotation coverage, the description supplies everything an agent needs: valid inputs, filtering modes, error behaviors, the response envelope, and a binding-text limitation. The caveat that the ICC publication prevails is exactly the kind of scope limit an agent should surface.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter semantics the schema cannot express: 'full' applies only to list calls while a single-record call always returns the full record, and lists default to every summary row versus 5 with full: true. It also notes that responses carry total and next_offset, tying offset/limit to pagination behavior.

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

Purpose5/5

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

Opens with a specific verb and resource ('Look up the 11 Incoterms 2020 trade rules') and enumerates the exact scope, including which 7 rules are any-mode and which 4 are sea-only. It distinguishes the three call shapes (single code, category filter, no filter) so an agent can tell it apart from siblings like hs_code_lookup or uk_duty_calculator.

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

Usage Guidelines5/5

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

Explicitly states the selection logic: 'Provide code for one rule, category ... for a filtered list, or neither to list all 11.' It also names the related tools and the specific relationship (uk_duty_calculator accepts an incoterm when composing the CIF value; shipment_summary for composite analysis), which routes the agent correctly.

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

All FreightUtils MCP Server tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.