Skip to main content
Glama

Border prices: customs unit values per kilogram

pricepaid_border_prices
Read-onlyIdempotent

Use this when a user asks what traded goods are worth at the border, per kilogram, as declared to customs: for example what a country pays per kg to import wheat, diesel, cheese or timber, or earns per kg exporting whisky or steel, in the EU member states listed (country FR, DE, ES, IT, NL, BE, IE, PL, PT, DK, SE) or the United Kingdom (country GB), optionally from or to one partner country. Returns the customs value divided by the net weight (a value-weighted average per kg in the reporting country's currency), a range between the 10th and 90th percentile of the individual customs lines weighted by weight, the months it covers, the biggest partner countries and the official source and licence. This is a customs unit value (price_type official_statistic) built from declared trade values and weights, not a shelf price, not a wholesale quote and not a receipt, so there is no sample size. How fresh: the EU member states listed: monthly: Eurostat publishes each month's trade statistics about 2.5 months after the month ends; our figures are read live and each answer states its months; the United Kingdom: monthly: HMRC publishes each month's trade statistics about six weeks after the month ends; our figures are read live and each answer states its months. Do not use for what a shopper pays in a shop, for a single contract or shipment, for futures or spot quotes, for services, or for countries that are not listed.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "country": "<country>",
      "product": "<product>"
    },
    "name": "pricepaid_border_prices"
  }
}

Input Schema

NameRequiredDescriptionDefault
monthsNoHow many months to include, ending with the period. Default 1. More months smooth out lumpy shipments. EU: months to include, 1 to 12 (default 1). GB: months to include, 1 to 12 (default 1).
periodNoOptional last month to include, as YYYY-MM. Default: the newest month the customs authority has published. EU: the last month to include (YYYY-MM). Eurostat publishes about 2.5 months after the month ends; default is the newest published…
countryYesFR, DE, ES, IT, NL, BE, IE, PL, PT, DK, SE = EU member states (Eurostat Comext: customs value per kilogram of goods imported or exported, by customs commodity code and partner country, monthly); GB = United Kingdom (HMRC Overseas Trade Statistics: customs…
partnerNoOptional partner country (ISO code such as 'DE' or 'US', or its name): where the goods came from (imports) or went to (exports). Leave out for all partners. EU: optional partner country, as a 2-letter ISO code (DE, US, CN, BR ...) or…
productYesThe goods: an everyday word such as 'wheat', 'diesel', 'cheese', 'timber', 'steel', 'whisky', or a customs commodity code (HS/CN) of 4 to 8 digits such as '1001' or '271019'. EU: an everyday word (diesel, petrol, crude oil, natural gas…
directionNoGoods coming in (imports, default) or going out (exports). EU: imports (default) or exports of the country asked about, trade with all other countries. GB: imports (default) or exports, as the UK reports them (EU and non-EU trade combined).

Output Schema

NameRequiredDescriptionDefault
priceNo
periodNo
sourceNo
statusYes
summaryYesOne sentence an AI can quote.
confidenceNohigh, medium, low or insufficient.
sample_sizeNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed36 schema fields changed
    • changedInput schema / properties / country / description
      Previous value: -"FR, DE, ES, IT, NL, BE, IE, PL, PT, DK, SE = EU member states (Eurostat Comext: customs value per kilogram of goods imported or exported, by customs commodity code and partner country, monthly); GB = United Kingdom (HMRC Overseas Trade Statistics: customs value per kilogram of goods imported or exported, by customs commodity code and partner country, monthly)"New value: +"FR, DE, ES, IT, NL, BE, IE, PL, PT, DK, SE = EU member states (Eurostat Comext: customs value per kilogram of goods imported or exported, by customs commodity code and partner country, monthly); GB = United Kingdom (HMRC Overseas Trade Statistics: customs…"
    • changedInput schema / properties / partner / description
      Previous value: -"Optional partner country (ISO code such as 'DE' or 'US', or its name): where the goods came from (imports) or went to (exports). Leave out for all partners. EU: optional partner country, as a 2-letter ISO code (DE, US, CN, BR ...) or common name. GB: optional partner country, as an ISO code (DE, US, CN, FR, NL, IE ...) or HMRC's country name."New value: +"Optional partner country (ISO code such as 'DE' or 'US', or its name): where the goods came from (imports) or went to (exports). Leave out for all partners. EU: optional partner country, as a 2-letter ISO code (DE, US, CN, BR ...) or…"
    • changedInput schema / properties / period / description
      Previous value: -"Optional last month to include, as YYYY-MM. Default: the newest month the customs authority has published. EU: the last month to include (YYYY-MM). Eurostat publishes about 2.5 months after the month ends; default is the newest published month. GB: the last month to include (YYYY-MM). HMRC publishes about six weeks after the month ends; default is the newest published month."New value: +"Optional last month to include, as YYYY-MM. Default: the newest month the customs authority has published. EU: the last month to include (YYYY-MM). Eurostat publishes about 2.5 months after the month ends; default is the newest published…"
    • changedInput schema / properties / product / description
      Previous value: -"The goods: an everyday word such as 'wheat', 'diesel', 'cheese', 'timber', 'steel', 'whisky', or a customs commodity code (HS/CN) of 4 to 8 digits such as '1001' or '271019'. EU: an everyday word (diesel, petrol, crude oil, natural gas, wheat, barley, maize, rice, sugar, coffee, tea, cocoa and more) or a customs commodity code of 4, 6 or 8 digits (HS/CN, e.g. 1001 wheat, 271019 diesel, 0406 cheese). A code groups different products, so the average depends on the mix. GB: an everyday word (diesel, petrol, crude oil, wheat, barley, maize, rice, sugar, coffee, tea, cocoa, apples and more) or a customs commodity code of 4 to 8 digits (HS/CN, e.g. 1001 wheat, 2710 19 diesel, 0406 cheese). A code groups different products, so the average depends on the mix."New value: +"The goods: an everyday word such as 'wheat', 'diesel', 'cheese', 'timber', 'steel', 'whisky', or a customs commodity code (HS/CN) of 4 to 8 digits such as '1001' or '271019'. EU: an everyday word (diesel, petrol, crude oil, natural gas…"
    • changedOutput schema / description
      Previous value: -"A price answer: a range or an official statistic with sample size, period, confidence, source and licence."New value: +"Price range from real records: price, sample_size, period, confidence, source and licence."
    • removedOutput schema / properties / answer_id
      Removed value: -{
      -  "description": "Audit trail: a stable id (hash of source id, normalised query, data period and method_version). The same question on the same data gives the same id; keep it with the reasoning that used the figure.",
      -  "type": "string"
      -}
    • removedOutput schema / properties / as_of
      Removed value: -{
      -  "description": "When the answer was produced (ISO 8601); the snapshot date when the official source was down and the answer comes from our copy.",
      -  "type": "string"
      -}
    • changedOutput schema / properties / confidence / description
      Previous value: -"high = 50+ records, medium = 15–49, low = 5–14."New value: +"high, medium, low or insufficient."
    • removedOutput schema / properties / confidence / enum
      Removed value: -[
      -  "high",
      -  "medium",
      -  "low",
      -  "insufficient"
      -]
    • removedOutput schema / properties / data_age_days
      Removed value: -{
      -  "description": "Whole days between data_as_of and retrieved_at; null when data_as_of is null.",
      -  "type": [
      -    "number",
      -    "null"
      -  ]
      -}
    • removedOutput schema / properties / data_as_of
      Removed value: -{
      -  "description": "ISO date (YYYY-MM-DD) of the newest data point behind the figure; null when unknown.",
      -  "type": [
      -    "string",
      -    "null"
      -  ]
      -}
    • removedOutput schema / properties / evidence
      Removed value: -{
      -  "additionalProperties": {},
      -  "description": "Audit trail: what kind of evidence the figure is.",
      -  "properties": {
      -    "label": {
      -      "description": "Short name of the kind of evidence, e.g. 'Recorded sale prices', 'Official published average', 'Official published index', 'Posted shelf or pump price', 'Posted or listed price', 'Contract award value', 'Regulated reimbursement price'.",
      -      "type": "string"
      -    },
      -    "meaning": {
      -      "description": "One sentence on what this kind of evidence does and does not establish.",
      -      "type": "string"
      -    },
      -    "type": {
      -      "description": "Same as price_type.",
      -      "type": "string"
      -    }
      -  },
      -  "required": [
      -    "type",
      -    "label",
      -    "meaning"
      -  ],
      -  "type": "object"
      -}
    • removedOutput schema / properties / extra
      Removed value: -{
      -  "additionalProperties": {},
      -  "description": "Source-specific details (for example cheapest stations). extra.stale is true when the answer comes from our copy of the source.",
      -  "propertyNames": {
      -    "type": "string"
      -  },
      -  "type": "object"
      -}
    • removedOutput schema / properties / method
      Removed value: -{
      -  "type": "string"
      -}
    • removedOutput schema / properties / method_url
      Removed value: -{
      -  "type": "string"
      -}
    • removedOutput schema / properties / method_version
      Removed value: -{
      -  "description": "Audit trail: version of the way this source turns raw data into an answer (per source, default '1').",
      -  "type": "string"
      -}
    • removedOutput schema / properties / notice
      Removed value: -{
      -  "description": "Information, not a valuation or offer. Also says when the answer is our copy because the official source did not respond.",
      -  "type": "string"
      -}
    • removedOutput schema / properties / period / description
      Removed value: -"The period the records cover (ISO dates), or the date of the snapshot when the answer comes from our copy."
    • changedOutput schema / properties / price / anyOf
      Previous value: -[
      -  {
      -    "additionalProperties": {},
      -    "description": "The price. Null when there is not enough data to publish a figure (fewer than 5 records) or nothing matched.",
      -    "properties": {
      -      "currency": {
      -        "description": "ISO 4217 currency code, e.g. EUR.",
      -        "type": "string"
      -      },
      -      "max": {
      -        "type": [
      -          "number",
      -          "null"
      -        ]
      -      },
      -      "measure": {
      -        "description": "What value is: median for ranges built from records; average or median for official statistics.",
      -        "enum": [
      -          "median",
      -          "average"
      -        ],
      -        "type": "string"
      -      },
      -      "median": {
      -        "type": [
      -          "number",
      -          "null"
      -        ]
      -      },
      -      "min": {
      -        "type": [
      -          "number",
      -          "null"
      -        ]
      -      },
      -      "typical_high": {
      -        "description": "90th percentile; null for official statistics that give no range.",
      -        "type": [
      -          "number",
      -          "null"
      -        ]
      -      },
      -      "typical_low": {
      -        "description": "10th percentile; null for official statistics that give no range.",
      -        "type": [
      -          "number",
      -          "null"
      -        ]
      -      },
      -      "unit": {
      -        "description": "What the price is per, e.g. 'per litre', 'per home', 'per kWh'.",
      -        "type": "string"
      -      },
      -      "value": {
      -        "description": "The headline figure. For ranges built from records it equals median.",
      -        "type": "number"
      -      }
      -    },
      -    "required": [
      -      "currency",
      -      "unit",
      -      "value"
      -    ],
      -    "type": "object"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "additionalProperties": {},
      +    "properties": {
      +      "currency": {
      +        "type": "string"
      +      },
      +      "typical_high": {
      +        "type": [
      +          "number",
      +          "null"
      +        ]
      +      },
      +      "typical_low": {
      +        "type": [
      +          "number",
      +          "null"
      +        ]
      +      },
      +      "unit": {
      +        "type": "string"
      +      },
      +      "value": {
      +        "type": "number"
      +      }
      +    },
      +    "required": [
      +      "currency",
      +      "unit",
      +      "value"
      +    ],
      +    "type": "object"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • removedOutput schema / properties / price_type
      Removed value: -{
      -  "description": "transaction, posted_pump_price, posted_price, contract_price, reimbursement_price or official_statistic.",
      -  "type": "string"
      -}
    • removedOutput schema / properties / query
      Removed value: -{
      -  "additionalProperties": {},
      -  "description": "The request as understood, echoed back.",
      -  "propertyNames": {
      -    "type": "string"
      -  },
      -  "type": "object"
      -}
    • removedOutput schema / properties / reliability
      Removed value: -{
      -  "description": "How far to trust the figure as a distribution of real prices. official_with_count = a published official figure with a record count; official_median_no_count = a published average or median with no record count (confidence 'high' there means the publisher is official, not that a count was checked); record_level = 15+ records we hold; thin = 5–14 records; stale = our copy because the official source did not respond; insufficient_data = no figure published.",
      -  "enum": [
      -    "official_with_count",
      -    "official_median_no_count",
      -    "record_level",
      -    "thin",
      -    "stale",
      -    "insufficient_data"
      -  ],
      -  "type": "string"
      -}
    • removedOutput schema / properties / retrieved_at
      Removed value: -{
      -  "description": "Audit trail: when ProofPrice produced this answer (ISO 8601). For an answer from our own copy this is now, while as_of is the snapshot date.",
      -  "type": "string"
      -}
    • removedOutput schema / properties / sample_size / description
      Removed value: -"Number of records behind the figure; null when the publisher does not say."
    • removedOutput schema / properties / source / description
      Removed value: -"Where the figure comes from, under which licence, and the attribution line to show."
    • removedOutput schema / properties / source / properties / attribution / description
      Removed value: -"The attribution line to show with the figure."
    • removedOutput schema / properties / source / properties / id
      Removed value: -{
      -  "description": "Source id, e.g. es-fuel.",
      -  "type": "string"
      -}
    • removedOutput schema / properties / source / properties / licence_url
      Removed value: -{
      -  "type": "string"
      -}
    • removedOutput schema / properties / source / properties / publisher
      Removed value: -{
      -  "description": "Who publishes the data.",
      -  "type": "string"
      -}
    • removedOutput schema / properties / source / properties / url
      Removed value: -{
      -  "description": "The publisher's page for this data.",
      -  "type": "string"
      -}
    • changedOutput schema / properties / source / required
      Previous value: -[
      -  "id",
      -  "name",
      -  "publisher",
      -  "licence",
      -  "licence_url",
      -  "attribution",
      -  "url"
      -]New value: +[
      +  "name",
      +  "licence",
      +  "attribution"
      +]
    • removedOutput schema / properties / statistic
      Removed value: -{
      -  "additionalProperties": {},
      -  "description": "Official statistics only: what kind of figure it is and the period the publisher states it for.",
      -  "properties": {
      -    "measure": {
      -      "enum": [
      -        "median",
      -        "average"
      -      ],
      -      "type": "string"
      -    },
      -    "note": {
      -      "type": "string"
      -    },
      -    "reference_period": {
      -      "type": "string"
      -    }
      -  },
      -  "required": [
      -    "measure",
      -    "reference_period"
      -  ],
      -  "type": "object"
      -}
    • removedOutput schema / properties / status / description
      Removed value: -"ok = a figure is returned; insufficient_data = fewer than 5 matching records; no_matches = nothing matched."
    • removedOutput schema / properties / suggestions
      Removed value: -{
      -  "description": "Short plain things to try next: widen the period or area, ask for an itemised quote. May be empty.",
      -  "items": {
      -    "type": "string"
      -  },
      -  "type": "array"
      -}
    • changedOutput schema / properties / summary / description
      Previous value: -"One plain sentence an AI can quote."New value: +"One sentence an AI can quote."
    • changedOutput schema / required
      Previous value: -[
      -  "query",
      -  "status",
      -  "source",
      -  "summary",
      -  "notice"
      -]New value: +[
      +  "status",
      +  "summary"
      +]
  2. Changed7 schema fields changed
    • changedInput schema / properties / country / description
      Previous value: -"GB = United Kingdom (HMRC Overseas Trade Statistics: customs value per kilogram of goods imported or exported, by customs commodity code and partner country, monthly)"New value: +"FR, DE, ES, IT, NL, BE, IE, PL, PT, DK, SE = EU member states (Eurostat Comext: customs value per kilogram of goods imported or exported, by customs commodity code and partner country, monthly); GB = United Kingdom (HMRC Overseas Trade Statistics: customs value per kilogram of goods imported or exported, by customs commodity code and partner country, monthly)"
    • changedInput schema / properties / country / enum
      Previous value: -[
      -  "GB"
      -]New value: +[
      +  "FR",
      +  "DE",
      +  "ES",
      +  "IT",
      +  "NL",
      +  "BE",
      +  "IE",
      +  "PL",
      +  "PT",
      +  "DK",
      +  "SE",
      +  "GB"
      +]
    • changedInput schema / properties / direction / description
      Previous value: -"Goods coming in (imports, default) or going out (exports). GB: imports (default) or exports, as the UK reports them (EU and non-EU trade combined)."New value: +"Goods coming in (imports, default) or going out (exports). EU: imports (default) or exports of the country asked about, trade with all other countries. GB: imports (default) or exports, as the UK reports them (EU and non-EU trade combined)."
    • changedInput schema / properties / months / description
      Previous value: -"How many months to include, ending with the period. Default 1. More months smooth out lumpy shipments. GB: months to include, 1 to 12 (default 1)."New value: +"How many months to include, ending with the period. Default 1. More months smooth out lumpy shipments. EU: months to include, 1 to 12 (default 1). GB: months to include, 1 to 12 (default 1)."
    • changedInput schema / properties / partner / description
      Previous value: -"Optional partner country (ISO code such as 'DE' or 'US', or its name): where the goods came from (imports) or went to (exports). Leave out for all partners. GB: optional partner country, as an ISO code (DE, US, CN, FR, NL, IE ...) or HMRC's country name."New value: +"Optional partner country (ISO code such as 'DE' or 'US', or its name): where the goods came from (imports) or went to (exports). Leave out for all partners. EU: optional partner country, as a 2-letter ISO code (DE, US, CN, BR ...) or common name. GB: optional partner country, as an ISO code (DE, US, CN, FR, NL, IE ...) or HMRC's country name."
    • changedInput schema / properties / period / description
      Previous value: -"Optional last month to include, as YYYY-MM. Default: the newest month the customs authority has published. GB: the last month to include (YYYY-MM). HMRC publishes about six weeks after the month ends; default is the newest published month."New value: +"Optional last month to include, as YYYY-MM. Default: the newest month the customs authority has published. EU: the last month to include (YYYY-MM). Eurostat publishes about 2.5 months after the month ends; default is the newest published month. GB: the last month to include (YYYY-MM). HMRC publishes about six weeks after the month ends; default is the newest published month."
    • changedInput schema / properties / product / description
      Previous value: -"The goods: an everyday word such as 'wheat', 'diesel', 'cheese', 'timber', 'steel', 'whisky', or a customs commodity code (HS/CN) of 4 to 8 digits such as '1001' or '271019'. GB: an everyday word (diesel, petrol, crude oil, wheat, barley, maize, rice, sugar, coffee, tea, cocoa, apples and more) or a customs commodity code of 4 to 8 digits (HS/CN, e.g. 1001 wheat, 2710 19 diesel, 0406 cheese). A code groups different products, so the average depends on the mix."New value: +"The goods: an everyday word such as 'wheat', 'diesel', 'cheese', 'timber', 'steel', 'whisky', or a customs commodity code (HS/CN) of 4 to 8 digits such as '1001' or '271019'. EU: an everyday word (diesel, petrol, crude oil, natural gas, wheat, barley, maize, rice, sugar, coffee, tea, cocoa and more) or a customs commodity code of 4, 6 or 8 digits (HS/CN, e.g. 1001 wheat, 271019 diesel, 0406 cheese). A code groups different products, so the average depends on the mix. GB: an everyday word (diesel, petrol, crude oil, wheat, barley, maize, rice, sugar, coffee, tea, cocoa, apples and more) or a customs commodity code of 4 to 8 digits (HS/CN, e.g. 1001 wheat, 2710 19 diesel, 0406 cheese). A code groups different products, so the average depends on the mix."
  3. Added

TDQS

A4.3/5.0
Behavior4/5

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds substantial context they cannot: per-source publication lags (Eurostat ~2.5 months, HMRC ~six weeks), live-read freshness, that the answer states which months it covers, the currency of the average, and the value-weighted 10th–90th percentile range. It also explains there is no sample size because this is a customs unit value — a genuinely useful disclosure for interpreting results. Slightly short of 5 only because output format detail overlaps what the output schema presumably carries.

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

Conciseness3/5

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

Well front-loaded — the use case and metric come first, exclusions last. However, the freshness paragraph and the 'not a shelf price / not a wholesale quote / not a receipt' phrasing partly duplicate the later do-not-use list, and the definition is long enough that an agent must parse two overlapping passages to extract the same constraint.

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 live statistical lookup with six parameters and an output schema, the description covers provenance, freshness per source, currency basis, aggregation method, and scope limits. Nothing an agent needs in order to decide whether to call this tool, or to explain its answer to a user, is missing.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already explains country, partner, product, months, period, and direction in detail. The description reinforces the partner semantics ('from or to one partner country') and the country list, but adds little that the parameter descriptions don't already state. Baseline 3 is appropriate.

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?

States a specific verb and resource — what traded goods are worth at the border per kilogram as declared to customs — and names concrete examples (wheat, diesel, cheese, timber, whisky, steel). It explicitly distinguishes the metric from adjacent siblings: 'not a shelf price, not a wholesale quote and not a receipt.' An agent can route correctly without opening the schema.

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?

Gives an explicit when-to-use trigger ('when a user asks what traded goods are worth at the border, per kilogram') and an explicit when-not list: shopper prices, single contracts or shipments, futures/spot quotes, services, and unlisted countries. The supported country set is enumerated, so the agent knows the boundary condition before calling.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.