Skip to main content
Glama

Resolve Product Code

resolve_product_code
Read-onlyIdempotent

Resolve a free-text query or CN code(s) into validated customs code(s) with descriptions -- the recommended first step before using a code as customs_code in any other tool's query. Saves the search -> validate -> (optional) subtree round-trip: a bare keyword runs a search, a single code (or comma-separated list) is validated and described directly.

Tip: Comext/CN nomenclature is frequently coarser than a colloquial product name (e.g. there is no code for "glass jars" alone -- only heading 7010, which bundles jars with bottles, flasks and closures). Check has_subcodes and, if useful, set include_children=true to see whether a finer sub-code is actually a better match before committing to one code for a whole report.

Returns {mode, query, data}: data is the typed validation or search response. A single-code validation also carries subtree when requested.

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": {
      "query": "<query>"
    },
    "name": "resolve_product_code"
  }
}

Input Schema

NameRequiredDescriptionDefault
langNoLanguage for translated labels in the response; any other language is refused.en
limitNoMax keyword-search results (ignored for direct code validation).
queryYesFree-text keyword (e.g. 'glass jars') OR one or more CN codes, comma-separated (e.g. '7010' or '7010, 7013'), OR a single residual customs code (850440XX, 85SSS999, 85SSS).
include_childrenNoWhen resolving a single direct code, also fetch its immediate CN subtree so finer-grained alternatives are visible in one call.

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changed
    • changedOutput schema / $defs / SearchResolution / required
      Previous value: -[
      -  "query",
      -  "data"
      -]New value: +[
      +  "mode",
      +  "query",
      +  "data"
      +]
    • changedOutput schema / $defs / SearchResponse / required
      Previous value: -[
      -  "query",
      -  "lang",
      -  "source",
      -  "results"
      -]New value: +[
      +  "query",
      +  "lang",
      +  "source",
      +  "matched_prodcom",
      +  "results"
      +]
    • changedOutput schema / $defs / SearchResult / required
      Previous value: -[
      -  "code"
      -]New value: +[
      +  "code",
      +  "label",
      +  "path",
      +  "via_prodcom"
      +]
    • changedOutput schema / $defs / ValidateCustomsCodeResponse / required
      Previous value: -[
      -  "customs_code"
      -]New value: +[
      +  "customs_code",
      +  "levels",
      +  "customs_code_label",
      +  "has_subcodes",
      +  "interpreted_from",
      +  "residual_kind",
      +  "residual_spelling",
      +  "residual_reason",
      +  "in_eurostat_api",
      +  "residual_customs_codes",
      +  "in_current_cn",
      +  "segment_history"
      +]
    • changedOutput schema / $defs / ValidateResolution / required
      Previous value: -[
      -  "query",
      -  "data"
      -]New value: +[
      +  "mode",
      +  "query",
      +  "data"
      +]
  2. Changed7 schema fields changed
    • changedInput schema / properties / lang / description
      Previous value: -"Language for translated labels in the response. One of: bg, cs, da, de, el, en, es, et, fi, fr, ga, hr, hu, it, lt, lv, mt, nl, pl, pt, ro, sk, sl, sv."New value: +"Language for translated labels in the response; any other language is refused."
    • addedInput schema / properties / lang / enum
      Added value: +[
      +  "bg",
      +  "cs",
      +  "da",
      +  "de",
      +  "el",
      +  "en",
      +  "es",
      +  "et",
      +  "fi",
      +  "fr",
      +  "ga",
      +  "hr",
      +  "hu",
      +  "it",
      +  "lt",
      +  "lv",
      +  "mt",
      +  "nl",
      +  "pl",
      +  "pt",
      +  "ro",
      +  "sk",
      +  "sl",
      +  "sv"
      +]
    • changedInput schema / properties / query / description
      Previous value: -"Free-text keyword (e.g. 'glass jars') OR one or more CN codes, comma-separated (e.g. '7010' or '7010, 7013')."New value: +"Free-text keyword (e.g. 'glass jars') OR one or more CN codes, comma-separated (e.g. '7010' or '7010, 7013'), OR a single residual customs code (850440XX, 85SSS999, 85SSS)."
    • addedOutput schema / $defs
      Added value: +{
      +  "CodeLabel_CustomsCode_": {
      +    "additionalProperties": false,
      +    "properties": {
      +      "customs_code": {
      +        "description": "A canonical customs code, TOTAL, or a supported residual spelling.",
      +        "type": "string"
      +      },
      +      "text": {
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "customs_code",
      +      "text"
      +    ],
      +    "type": "object"
      +  },
      +  "DescriptionLevel": {
      +    "additionalProperties": false,
      +    "description": "One level of a customs code's description hierarchy, chapter first\n(``ComextNomenclature.get_description_levels``, plus the synthetic\nlevels of residual spellings and the dated levels of former editions).\n\nThe optional flags are sparse on the wire: present when true, absent\notherwise (the shape of the nomenclature layer's raw dicts).",
      +    "properties": {
      +      "customs_code": {
      +        "description": "The level's customs code.",
      +        "type": "string"
      +      },
      +      "is_catch_all": {
      +        "anyOf": [
      +          {
      +            "type": "boolean"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "default": null,
      +        "description": "True for a catch-all ('other') level."
      +      },
      +      "residual": {
      +        "anyOf": [
      +          {
      +            "type": "boolean"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "default": null,
      +        "description": "True for the synthetic level of a residual spelling."
      +      },
      +      "segment": {
      +        "anyOf": [
      +          {
      +            "type": "boolean"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "default": null,
      +        "description": "True for a historical segment's own definition."
      +      },
      +      "siblings": {
      +        "anyOf": [
      +          {
      +            "items": {
      +              "$ref": "#/$defs/CodeLabel_CustomsCode_"
      +            },
      +            "type": "array"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "default": null,
      +        "description": "For a catch-all level, the ordinary siblings it excludes."
      +      },
      +      "text": {
      +        "description": "The level's label, in the requested language.",
      +        "type": "string"
      +      },
      +      "untranslated": {
      +        "anyOf": [
      +          {
      +            "type": "boolean"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "default": null,
      +        "description": "True when the label fell back to English."
      +      },
      +      "window": {
      +        "anyOf": [
      +          {
      +            "$ref": "#/$defs/SegmentWindow"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "default": null,
      +        "description": "For a level read from a dated edition (a former definition, or one of its ancestors as that edition had them): the validity window of the definition shown. Absent for current-edition levels."
      +      }
      +    },
      +    "required": [
      +      "customs_code",
      +      "text"
      +    ],
      +    "type": "object"
      +  },
      +  "MatchedProdcom": {
      +    "additionalProperties": false,
      +    "description": "The PRODCOM code resolved from a dotted search query.",
      +    "properties": {
      +      "description": {
      +        "anyOf": [
      +          {
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "description": "The code's label, when the nomenclature lists one."
      +      },
      +      "prodcom_code": {
      +        "description": "The resolved PRODCOM code, in dotted form.",
      +        "examples": [
      +          "23.99.14",
      +          "24.10.T3.40"
      +        ],
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "prodcom_code",
      +      "description"
      +    ],
      +    "type": "object"
      +  },
      +  "RecordedLinkPayload": {
      +    "additionalProperties": false,
      +    "description": "One recorded predecessor/successor edge of an exact segment.",
      +    "properties": {
      +      "customs_code": {
      +        "description": "The other segment's customs code.",
      +        "type": "string"
      +      },
      +      "marker": {
      +        "description": "Eurostat's relation marker, as recorded.",
      +        "type": "string"
      +      },
      +      "match": {
      +        "$ref": "#/$defs/WireEnum_LinkMatch_",
      +        "description": "'matched' when the endpoint resolves to a recorded segment by its full window, 'unmatched' otherwise (never attached to a guessed segment)."
      +      },
      +      "valid_from": {
      +        "description": "The other segment's window start, ISO date.",
      +        "type": "string"
      +      },
      +      "valid_to": {
      +        "anyOf": [
      +          {
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "description": "The other segment's window end, ISO date; null when open."
      +      }
      +    },
      +    "required": [
      +      "customs_code",
      +      "valid_from",
      +      "valid_to",
      +      "marker",
      +      "match"
      +    ],
      +    "type": "object"
      +  },
      +  "RecordedLinksPayload": {
      +    "additionalProperties": false,
      +    "properties": {
      +      "predecessors": {
      +        "description": "Edges recorded into this segment.",
      +        "items": {
      +          "$ref": "#/$defs/RecordedLinkPayload"
      +        },
      +        "type": "array"
      +      },
      +      "successors": {
      +        "description": "Edges recorded from this segment.",
      +        "items": {
      +          "$ref": "#/$defs/RecordedLinkPayload"
      +        },
      +        "type": "array"
      +      }
      +    },
      +    "required": [
      +      "successors",
      +      "predecessors"
      +    ],
      +    "type": "object"
      +  },
      +  "ResolveProductCodeResponse": {
      +    "discriminator": {
      +      "mapping": {
      +        "search": "#/$defs/SearchResolution",
      +        "validate": "#/$defs/ValidateResolution"
      +      },
      +      "propertyName": "mode"
      +    },
      +    "oneOf": [
      +      {
      +        "$ref": "#/$defs/ValidateResolution"
      +      },
      +      {
      +        "$ref": "#/$defs/SearchResolution"
      +      }
      +    ]
      +  },
      +  "SearchResolution": {
      +    "additionalProperties": false,
      +    "description": "A nomenclature search response and the caller's original query.",
      +    "properties": {
      +      "data": {
      +        "$ref": "#/$defs/SearchResponse"
      +      },
      +      "mode": {
      +        "const": "search",
      +        "default": "search",
      +        "type": "string"
      +      },
      +      "query": {
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "query",
      +      "data"
      +    ],
      +    "type": "object"
      +  },
      +  "SearchResponse": {
      +    "additionalProperties": false,
      +    "description": "GET /api/reference/search — ranked candidates; ``matched_prodcom`` is\nset when the query was a dotted PRODCOM notation.",
      +    "properties": {
      +      "lang": {
      +        "description": "The label language used.",
      +        "enum": [
      +          "bg",
      +          "cs",
      +          "da",
      +          "de",
      +          "el",
      +          "en",
      +          "es",
      +          "et",
      +          "fi",
      +          "fr",
      +          "ga",
      +          "hr",
      +          "hu",
      +          "it",
      +          "lt",
      +          "lv",
      +          "mt",
      +          "nl",
      +          "pl",
      +          "pt",
      +          "ro",
      +          "sk",
      +          "sl",
      +          "sv"
      +        ],
      +        "type": "string"
      +      },
      +      "matched_prodcom": {
      +        "anyOf": [
      +          {
      +            "$ref": "#/$defs/MatchedProdcom"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "default": null,
      +        "description": "The resolved PRODCOM code descriptor, when the query used PRODCOM notation (present even when no CN code maps)."
      +      },
      +      "query": {
      +        "description": "The query as received.",
      +        "type": "string"
      +      },
      +      "results": {
      +        "description": "The ranked candidates.",
      +        "items": {
      +          "$ref": "#/$defs/SearchResult"
      +        },
      +        "type": "array"
      +      },
      +      "source": {
      +        "$ref": "#/$defs/WireEnum_SearchSource_",
      +        "description": "The nomenclature searched ('cn', or 'prodcom' for PRODCOM-notation queries)."
      +      }
      +    },
      +    "required": [
      +      "query",
      +      "lang",
      +      "source",
      +      "results"
      +    ],
      +    "type": "object"
      +  },
      +  "SearchResult": {
      +    "additionalProperties": false,
      +    "description": "One ranked search candidate.",
      +    "properties": {
      +      "code": {
      +        "description": "The candidate's customs code.",
      +        "type": "string"
      +      },
      +      "label": {
      +        "anyOf": [
      +          {
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "default": null,
      +        "description": "The code's label, in the requested language; null for a mapped code the nomenclature does not list."
      +      },
      +      "path": {
      +        "anyOf": [
      +          {
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "default": null,
      +        "description": "The candidate's breadcrumb: its ancestor labels joined into one string; null alongside a null label."
      +      },
      +      "via_prodcom": {
      +        "anyOf": [
      +          {
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "default": null,
      +        "description": "The dotted PRODCOM form the match came through, for PRODCOM-notation queries."
      +      }
      +    },
      +    "required": [
      +      "code"
      +    ],
      +    "type": "object"
      +  },
      +  "SegmentHistoryEntry": {
      +    "additionalProperties": false,
      +    "description": "One recorded definition of a customs code with its direct recorded\nlinks (``SegmentHistoryPayload.segments``).",
      +    "properties": {
      +      "customs_code": {
      +        "description": "The customs code the segment defines.",
      +        "type": "string"
      +      },
      +      "kind": {
      +        "$ref": "#/$defs/WireEnum_SegmentKind_",
      +        "description": "The classification row's kind ('cn', 'residual_xx', 'letter_coded')."
      +      },
      +      "label": {
      +        "description": "The segment's own label (the definition in force during its window), in the requested language when available.",
      +        "type": "string"
      +      },
      +      "label_lang": {
      +        "description": "The label's language (English when the requested one is not recorded for this definition).",
      +        "enum": [
      +          "bg",
      +          "cs",
      +          "da",
      +          "de",
      +          "el",
      +          "en",
      +          "es",
      +          "et",
      +          "fi",
      +          "fr",
      +          "ga",
      +          "hr",
      +          "hu",
      +          "it",
      +          "lt",
      +          "lv",
      +          "mt",
      +          "nl",
      +          "pl",
      +          "pt",
      +          "ro",
      +          "sk",
      +          "sl",
      +          "sv"
      +        ],
      +        "type": "string"
      +      },
      +      "recorded_links": {
      +        "$ref": "#/$defs/RecordedLinksPayload",
      +        "description": "Direct correspondence edges recorded for this exact definition. An empty list means no recorded direct link -- not that the code never changed (headings have no edges of their own)."
      +      },
      +      "untranslated": {
      +        "anyOf": [
      +          {
      +            "type": "boolean"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "default": null,
      +        "description": "True when the label fell back to English."
      +      },
      +      "valid_from": {
      +        "description": "First day of the segment's validity window, ISO date.",
      +        "type": "string"
      +      },
      +      "valid_to": {
      +        "anyOf": [
      +          {
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "description": "Last day of the window, ISO date; null for a segment still in force."
      +      }
      +    },
      +    "required": [
      +      "customs_code",
      +      "valid_from",
      +      "valid_to",
      +      "kind",
      +      "label",
      +      "label_lang",
      +      "recorded_links"
      +    ],
      +    "type": "object"
      +  },
      +  "SegmentHistoryPayload": {
      +    "additionalProperties": false,
      +    "description": "Every recorded definition of one customs code (the CN classification\nfiles), independent of the current edition.",
      +    "properties": {
      +      "customs_code": {
      +        "description": "The base customs code.",
      +        "type": "string"
      +      },
      +      "metadata_generation": {
      +        "anyOf": [
      +          {
      +            "type": "integer"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "description": "The classification snapshot the history comes from."
      +      },
      +      "segments": {
      +        "description": "The definitions, oldest first.",
      +        "items": {
      +          "$ref": "#/$defs/SegmentHistoryEntry"
      +        },
      +        "type": "array"
      +      }
      +    },
      +    "required": [
      +      "customs_code",
      +      "metadata_generation",
      +      "segments"
      +    ],
      +    "type": "object"
      +  },
      +  "SegmentPayload": {
      +    "additionalProperties": false,
      +    "description": "One recorded definition of a customs code: a fact of the\nclassification metadata, with its window and its own label.",
      +    "properties": {
      +      "customs_code": {
      +        "description": "The customs code the segment defines.",
      +        "type": "string"
      +      },
      +      "kind": {
      +        "$ref": "#/$defs/WireEnum_SegmentKind_",
      +        "description": "The classification row's kind ('cn', 'residual_xx', 'letter_coded')."
      +      },
      +      "label": {
      +        "description": "The segment's own label (the definition in force during its window), in the requested language when available.",
      +        "type": "string"
      +      },
      +      "label_lang": {
      +        "description": "The label's language (English when the requested one is not recorded for this definition).",
      +        "enum": [
      +          "bg",
      +          "cs",
      +          "da",
      +          "de",
      +          "el",
      +          "en",
      +          "es",
      +          "et",
      +          "fi",
      +          "fr",
      +          "ga",
      +          "hr",
      +          "hu",
      +          "it",
      +          "lt",
      +          "lv",
      +          "mt",
      +          "nl",
      +          "pl",
      +          "pt",
      +          "ro",
      +          "sk",
      +          "sl",
      +          "sv"
      +        ],
      +        "type": "string"
      +      },
      +      "untranslated": {
      +        "anyOf": [
      +          {
      +            "type": "boolean"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "default": null,
      +        "description": "True when the label fell back to English."
      +      },
      +      "valid_from": {
      +        "description": "First day of the segment's validity window, ISO date.",
      +        "type": "string"
      +      },
      +      "valid_to": {
      +        "anyOf": [
      +          {
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "description": "Last day of the window, ISO date; null for a segment still in force."
      +      }
      +    },
      +    "required": [
      +      "customs_code",
      +      "valid_from",
      +      "valid_to",
      +      "kind",
      +      "label",
      +      "label_lang"
      +    ],
      +    "type": "object"
      +  },
      +  "SegmentWindow": {
      +    "additionalProperties": false,
      +    "description": "The validity window of one customs-code segment (one definition).",
      +    "properties": {
      +      "valid_from": {
      +        "description": "First day of the window, ISO date.",
      +        "type": "string"
      +      },
      +      "valid_to": {
      +        "anyOf": [
      +          {
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "description": "Last day of the window, ISO date; null while in force."
      +      }
      +    },
      +    "required": [
      +      "valid_from",
      +      "valid_to"
      +    ],
      +    "type": "object"
      +  },
      +  "SubcodeRow": {
      +    "additionalProperties": false,
      +    "description": "One sub-code or residual customs code row, shared by breakdown views\n(``subcode-compare``, ``concentration-compare``, ``volatility``) and\nvalidation responses (``ValidateCustomsCodeResponse.residual_customs_codes``).",
      +    "properties": {
      +      "basket_key": {
      +        "description": "The key of this row's basket in the payload's per-sub-code maps: the sub-code (read over the parent piece's window), or the entered basket's label.",
      +        "type": "string"
      +      },
      +      "customs_code": {
      +        "description": "The sub-code (or residual spelling).",
      +        "type": "string"
      +      },
      +      "in_eurostat_api": {
      +        "anyOf": [
      +          {
      +            "type": "boolean"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "default": null,
      +        "description": "For a residual row: whether Eurostat's API serves the spelling as a PRODUCT value (XX codes only)."
      +      },
      +      "label": {
      +        "description": "The label of the row's (latest) definition, in the requested language when recorded.",
      +        "type": "string"
      +      },
      +      "residual_kind": {
      +        "anyOf": [
      +          {
      +            "$ref": "#/$defs/WireEnum_ResidualKind_"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "default": null,
      +        "description": "For a residual row: 'xx' or 'letter'. Residual rows explain the gap between the sub-codes and the parent, and are pinned outside the top-N ranking."
      +      },
      +      "residual_reason": {
      +        "anyOf": [
      +          {
      +            "$ref": "#/$defs/WireEnum_ResidualReason_"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "default": null,
      +        "description": "For a letter code or reason group: the reason letter (S, Y, E, I, …)."
      +      },
      +      "residual_spelling": {
      +        "anyOf": [
      +          {
      +            "$ref": "#/$defs/WireEnum_ResidualSpelling_"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "default": null,
      +        "description": "For a residual row: 'xx', 'letter' or 'reason_group'."
      +      },
      +      "segments": {
      +        "description": "The definitions in force during the basket's window (empty for residual rows and for validation rows).",
      +        "items": {
      +          "$ref": "#/$defs/SegmentPayload"
      +        },
      +        "type": "array"
      +      },
      +      "untranslated": {
      +        "anyOf": [
      +          {
      +            "type": "boolean"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "default": null,
      +        "description": "True when the label fell back to English."
      +      }
      +    },
      +    "required": [
      +      "basket_key",
      +      "customs_code",
      +      "label",
      +      "segments"
      +    ],
      +    "type": "object"
      +  },
      +  "SubtreeNode": {
      +    "additionalProperties": false,
      +    "description": "One node of a CN sub-tree (recursive). The optional flags are sparse\non the wire: present when true (``siblings``: for catch-all nodes),\nabsent otherwise.",
      +    "properties": {
      +      "children": {
      +        "description": "The code's sub-codes.",
      +        "items": {
      +          "$ref": "#/$defs/SubtreeNode"
      +        },
      +        "type": "array"
      +      },
      +      "customs_code": {
      +        "description": "The node's customs code.",
      +        "type": "string"
      +      },
      +      "is_catch_all": {
      +        "anyOf": [
      +          {
      +            "type": "boolean"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "default": null,
      +        "description": "True for a catch-all ('other') node."
      +      },
      +      "siblings": {
      +        "anyOf": [
      +          {
      +            "items": {
      +              "$ref": "#/$defs/CodeLabel_CustomsCode_"
      +            },
      +            "type": "array"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "default": null,
      +        "description": "For a catch-all ('other') node, the ordinary siblings it excludes."
      +      },
      +      "text": {
      +        "description": "The code's label, in the requested language.",
      +        "type": "string"
      +      },
      +      "untranslated": {
      +        "anyOf": [
      +          {
      +            "type": "boolean"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "default": null,
      +        "description": "True when the label fell back to English."
      +      }
      +    },
      +    "required": [
      +      "customs_code",
      +      "text",
      +      "children"
      +    ],
      +    "type": "object"
      +  },
      +  "ValidateCustomsCodeBatchResponse": {
      +    "additionalProperties": false,
      +    "description": "The comma-separated batch path of validate-customs-code: each item a\nsuccess or an error.",
      +    "properties": {
      +      "results": {
      +        "description": "The results, one per input item, in input order.",
      +        "items": {
      +          "anyOf": [
      +            {
      +              "$ref": "#/$defs/ValidateCustomsCodeResponse"
      +            },
      +            {
      +              "$ref": "#/$defs/ValidateCustomsCodeError"
      +            }
      +          ]
      +        },
      +        "type": "array"
      +      }
      +    },
      +    "required": [
      +      "results"
      +    ],
      +    "type": "object"
      +  },
      +  "ValidateCustomsCodeError": {
      +    "additionalProperties": false,
      +    "description": "One batch item's failure shape.",
      +    "properties": {
      +      "customs_code": {
      +        "description": "The input item as typed.",
      +        "type": "string"
      +      },
      +      "error": {
      +        "$ref": "#/$defs/ValidateCustomsCodeErrorDetail",
      +        "description": "Why it failed."
      +      }
      +    },
      +    "required": [
      +      "customs_code",
      +      "error"
      +    ],
      +    "type": "object"
      +  },
      +  "ValidateCustomsCodeErrorDetail": {
      +    "additionalProperties": false,
      +    "properties": {
      +      "detail": {
      +        "description": "The error message.",
      +        "type": "string"
      +      },
      +      "status": {
      +        "description": "The HTTP status the single-code endpoint would have returned.",
      +        "type": "integer"
      +      }
      +    },
      +    "required": [
      +      "status",
      +      "detail"
      +    ],
      +    "type": "object"
      +  },
      +  "ValidateCustomsCodeResponse": {
      +    "additionalProperties": false,
      +    "description": "GET /api/reference/validate-customs-code/{customs_code} — a validated\ncustoms code with its description hierarchy.  Also one batch item's\nsuccess shape.",
      +    "properties": {
      +      "customs_code": {
      +        "description": "The validated, normalised customs code.",
      +        "type": "string"
      +      },
      +      "customs_code_label": {
      +        "default": "",
      +        "description": "The code's display label (the deepest level's text).",
      +        "type": "string"
      +      },
      +      "has_subcodes": {
      +        "default": false,
      +        "description": "Whether the code has children in the current CN edition.",
      +        "type": "boolean"
      +      },
      +      "in_current_cn": {
      +        "anyOf": [
      +          {
      +            "type": "boolean"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "default": null,
      +        "description": "For digit codes: whether the current CN edition lists the code. False for a code known only from its recorded history (expired or abolished)."
      +      },
      +      "in_eurostat_api": {
      +        "anyOf": [
      +          {
      +            "type": "boolean"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "default": null,
      +        "description": "For residual spellings: whether Eurostat's API serves the code as a PRODUCT value (XX codes only)."
      +      },
      +      "interpreted_from": {
      +        "anyOf": [
      +          {
      +            "type": "string"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "default": null,
      +        "description": "The raw input, when it was reformatted into customs_code (always the input as typed, never a note)."
      +      },
      +      "levels": {
      +        "description": "The code's CN description hierarchy (one entry per ancestor level), in the requested language.",
      +        "items": {
      +          "$ref": "#/$defs/DescriptionLevel"
      +        },
      +        "type": "array"
      +      },
      +      "residual_customs_codes": {
      +        "anyOf": [
      +          {
      +            "items": {
      +              "$ref": "#/$defs/SubcodeRow"
      +            },
      +            "type": "array"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "default": null,
      +        "description": "Residual customs codes related to this code: those directly under a digit code (its XX code plus one reason group per reason letter), or the letter codes inside a reason group."
      +      },
      +      "residual_kind": {
      +        "anyOf": [
      +          {
      +            "$ref": "#/$defs/WireEnum_ResidualKind_"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "default": null,
      +        "description": "Residual class for residual spellings: 'xx' or 'letter' (reason groups report 'letter', the class of the codes they group)."
      +      },
      +      "residual_reason": {
      +        "anyOf": [
      +          {
      +            "$ref": "#/$defs/WireEnum_ResidualReason_"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "default": null,
      +        "description": "The reason letter of a letter code or reason group (S, Y, E, I, …)."
      +      },
      +      "residual_spelling": {
      +        "anyOf": [
      +          {
      +            "$ref": "#/$defs/WireEnum_ResidualSpelling_"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "default": null,
      +        "description": "The residual spelling's exact shape: 'xx', 'letter' or 'reason_group'."
      +      },
      +      "segment_history": {
      +        "anyOf": [
      +          {
      +            "items": {
      +              "$ref": "#/$defs/SegmentHistoryPayload"
      +            },
      +            "type": "array"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "default": null,
      +        "description": "Every recorded definition of the code, with direct recorded links; null when no classification history is recorded for it. Use these windows to compose windowed pieces (the basket request form)."
      +      }
      +    },
      +    "required": [
      +      "customs_code"
      +    ],
      +    "type": "object"
      +  },
      +  "ValidateResolution": {
      +    "additionalProperties": false,
      +    "description": "A validated single/batch code response, optionally with its subtree.",
      +    "properties": {
      +      "data": {
      +        "anyOf": [
      +          {
      +            "$ref": "#/$defs/ValidateCustomsCodeResponse"
      +          },
      +          {
      +            "$ref": "#/$defs/ValidateCustomsCodeBatchResponse"
      +          }
      +        ]
      +      },
      +      "mode": {
      +        "const": "validate",
      +        "default": "validate",
      +        "type": "string"
      +      },
      +      "query": {
      +        "type": "string"
      +      },
      +      "subtree": {
      +        "anyOf": [
      +          {
      +            "$ref": "#/$defs/SubtreeNode"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ],
      +        "default": null
      +      }
      +    },
      +    "required": [
      +      "query",
      +      "data"
      +    ],
      +    "type": "object"
      +  },
      +  "WireEnum_LinkMatch_": {
      +    "enum": [
      +      "matched",
      +      "unmatched"
      +    ],
      +    "type": "string"
      +  },
      +  "WireEnum_ResidualKind_": {
      +    "enum": [
      +      "xx",
      +      "letter"
      +    ],
      +    "type": "string"
      +  },
      +  "WireEnum_ResidualReason_": {
      +    "enum": [
      +      "A",
      +      "B",
      +      "C",
      +      "E",
      +      "F",
      +      "I",
      +      "M",
      +      "P",
      +      "R",
      +      "S",
      +      "T",
      +      "V",
      +      "W",
      +      "Y"
      +    ],
      +    "type": "string"
      +  },
      +  "WireEnum_ResidualSpelling_": {
      +    "enum": [
      +      "xx",
      +      "letter",
      +      "reason_group"
      +    ],
      +    "type": "string"
      +  },
      +  "WireEnum_SearchSource_": {
      +    "description": "The nomenclature a search ran over: the CN index, or the PRODCOM\nreverse mapping a dotted-notation query is answered from.",
      +    "enum": [
      +      "cn",
      +      "prodcom"
      +    ],
      +    "type": "string"
      +  },
      +  "WireEnum_SegmentKind_": {
      +    "description": "The ingest classification of one CN.txt identity.",
      +    "enum": [
      +      "cn",
      +      "residual_xx",
      +      "letter_coded",
      +      "chapter_00",
      +      "other"
      +    ],
      +    "type": "string"
      +  }
      +}
    • changedOutput schema / additionalProperties
      Previous value: -trueNew value: +false
    • addedOutput schema / properties
      Added value: +{
      +  "result": {
      +    "$ref": "#/$defs/ResolveProductCodeResponse"
      +  }
      +}
    • addedOutput schema / required
      Added value: +[
      +  "result"
      +]
  3. Changed7 schema fields changed
    • addedInput schema / additionalProperties
      Added value: +false
    • removedInput schema / properties / include_children / title
      Removed value: -"Include Children"
    • removedInput schema / properties / lang / title
      Removed value: -"Lang"
    • removedInput schema / properties / limit / title
      Removed value: -"Limit"
    • removedInput schema / properties / query / title
      Removed value: -"Query"
    • removedInput schema / title
      Removed value: -"resolve_product_codeArguments"
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "additionalProperties": true,
      +  "type": "object"
      +}
  4. First observed

TDQS

A4.8/5.0
Behavior5/5

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive), but the description discloses behavior annotations cannot: the tool switches modes based on input shape, and a single-code validation additionally returns a `subtree` only when requested. The nomenclature-coarseness warning (no code for 'glass jars' alone, only heading 7010) surfaces a real domain pitfall that would otherwise cause silent misreporting.

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?

It is front-loaded with the core purpose and alternative-routing claim, then cleanly partitioned into a Tip and a Returns section. The Returns sentence is partially redundant with the existing output schema, though it earns some place by calling out the conditional `subtree` field.

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?

With annotations, a full-coverage schema and an output schema all present, the description fills the remaining gaps: mode selection, the coarse-nomenclature caveat, and the subtree escape hatch. Nothing an agent needs in order to invoke this correctly is missing.

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, and the description goes modestly beyond it by explaining why include_children matters (finer sub-code alternatives visible in one call) and by framing query as taking three distinct shapes. The remaining value-add is limited because the schema already documents the keyword/code/comma-list forms and the limit being ignored for validation.

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?

The description opens with a specific verb and resource: 'Resolve a free-text query or CN code(s) into validated customs code(s) with descriptions.' It explicitly positions itself against the search-then-validate-then-subtree workflow that siblings like validate_customs_code and get_subtree would otherwise require, so an agent can pick it without opening another 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?

It states both the when ('the recommended first step before using a code as customs_code in any other tool's query') and the mode-selection rule: a bare keyword runs a search, a single code or comma-separated list is validated directly. The tip adds a concrete decision procedure for include_children and has_subcodes, which is exactly the kind of conditional guidance an agent needs before committing a coarse heading to a whole report.

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.

Resources