Skip to main content
Glama

usitc-tariffs-mcp-server

Decode HTS references and published editions

usitc_list_reference
Read-onlyIdempotent

List accepted identifier formats, edition-pinned Special Program Indicators, chapter/section navigation labels, quantity units or published release metadata. Program names are decoded separately from country membership, which remains unknown without independently verified lists. Release records identify published editions but do not enable historical tariff lookup. Follow nextCursor for all entries.

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": {
      "topic": "<topic>"
    },
    "name": "usitc_list_reference"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoDefault 25; a larger value returns at most 100 items and says so. Keep the same limit when continuing with a cursor.
topicYesReference table to retrieve.
cursorNoOpaque nextCursor from the same tool with identical arguments.

Output Schema

NameRequiredDescriptionDefault
pageNoComplete reference count and continuation.
errorNoPresent when the call failed. Absent on success.
itemsNoComplete topic-specific records selected for this page.
topicNoRequested decoder or metadata topic.
noticeNoActionable next call for this particular empty result, followed by a disclosure when a requested limit above 100 was clamped.
sourceNoSource provenance.
decoderNoPresent for spi and units: provenance shared by every record on the page.
noticesNoPersistent source and coverage limitations.
releaseNoEdition checked for this result.
totalCountNoComplete locally filtered item count.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed6 schema fields changed
    • changedInput schema / properties / limit / description
      Previous value: -"Requested items as a positive safe integer; effectiveLimit discloses clamping to at most 100, and pages may be byte limited. Keep the same requested limit for continuation."New value: +"Default 25; a larger value returns at most 100 items and says so. Keep the same limit when continuing with a cursor."
    • addedOutput schema / properties / decoder
      Added value: +{
      +  "additionalProperties": false,
      +  "description": "Present for spi and units: provenance shared by every record on the page.",
      +  "properties": {
      +    "citation": {
      +      "description": "Official General Note citation for every record.",
      +      "type": "string"
      +    },
      +    "conditionality": {
      +      "description": "Legal qualification conditions for every program; spi only.",
      +      "type": "string"
      +    },
      +    "qualificationNotice": {
      +      "description": "Program qualification remains unresolved for every symbol; spi only.",
      +      "type": "string"
      +    },
      +    "sourceEdition": {
      +      "description": "Verification edition of this decoder table.",
      +      "type": "string"
      +    },
      +    "sourceUrl": {
      +      "description": "Edition-pinned official source.",
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "sourceEdition",
      +    "citation",
      +    "sourceUrl"
      +  ],
      +  "type": "object"
      +}
    • changedOutput schema / properties / items / items / anyOf
      Previous value: -[
      -  {
      -    "additionalProperties": false,
      -    "description": "One accepted tariff identifier format.",
      -    "properties": {
      -      "digits": {
      -        "description": "Digit count.",
      -        "maximum": 9007199254740991,
      -        "minimum": -9007199254740991,
      -        "type": "integer"
      -      },
      -      "format": {
      -        "description": "Conventional dotted format.",
      -        "type": "string"
      -      },
      -      "kind": {
      -        "const": "identifier",
      -        "description": "Identifier explanation.",
      -        "type": "string"
      -      },
      -      "meaning": {
      -        "description": "Hierarchy, inheritance or evidence semantics.",
      -        "type": "string"
      -      },
      -      "name": {
      -        "description": "Identifier kind.",
      -        "type": "string"
      -      }
      -    },
      -    "required": [
      -      "kind",
      -      "name",
      -      "digits",
      -      "format",
      -      "meaning"
      -    ],
      -    "type": "object"
      -  },
      -  {
      -    "additionalProperties": false,
      -    "description": "One edition-pinned program symbol and its qualification limits.",
      -    "properties": {
      -      "citation": {
      -        "description": "Official General Note citation.",
      -        "type": "string"
      -      },
      -      "conditionality": {
      -        "description": "Legal qualification conditions.",
      -        "type": "string"
      -      },
      -      "countryListCoverage": {
      -        "const": "unknown",
      -        "description": "Country membership has not been independently verified.",
      -        "type": "string"
      -      },
      -      "kind": {
      -        "const": "program",
      -        "description": "Reviewed program symbol record.",
      -        "type": "string"
      -      },
      -      "name": {
      -        "description": "Reviewed program name.",
      -        "type": "string"
      -      },
      -      "qualificationNotice": {
      -        "description": "Program qualification remains unresolved.",
      -        "type": "string"
      -      },
      -      "sourceEdition": {
      -        "description": "Verification edition of this decoder.",
      -        "type": "string"
      -      },
      -      "sourceUrl": {
      -        "description": "Edition-pinned official source.",
      -        "type": "string"
      -      },
      -      "symbol": {
      -        "description": "Exact SPI, preserving suffix punctuation.",
      -        "type": "string"
      -      }
      -    },
      -    "required": [
      -      "kind",
      -      "symbol",
      -      "name",
      -      "citation",
      -      "sourceUrl",
      -      "sourceEdition",
      -      "conditionality",
      -      "countryListCoverage",
      -      "qualificationNotice"
      -    ],
      -    "type": "object"
      -  },
      -  {
      -    "additionalProperties": false,
      -    "description": "One published chapter and its section navigation labels.",
      -    "properties": {
      -      "capturedAt": {
      -        "description": "Date the navigation labels were captured.",
      -        "type": "string"
      -      },
      -      "chapter": {
      -        "description": "Two-digit chapter number.",
      -        "type": "string"
      -      },
      -      "kind": {
      -        "const": "chapter",
      -        "description": "Published application navigation label.",
      -        "type": "string"
      -      },
      -      "label": {
      -        "description": "Published chapter title.",
      -        "type": "string"
      -      },
      -      "labelSource": {
      -        "const": "published_application_navigation",
      -        "description": "Label extraction provenance.",
      -        "type": "string"
      -      },
      -      "reserved": {
      -        "description": "Whether this chapter is reserved.",
      -        "type": "boolean"
      -      },
      -      "scheduleUrl": {
      -        "description": "Official tariff schedule.",
      -        "type": "string"
      -      },
      -      "section": {
      -        "description": "Published section identifier.",
      -        "type": "string"
      -      },
      -      "sectionLabel": {
      -        "description": "Published section title.",
      -        "type": "string"
      -      },
      -      "sourceUrl": {
      -        "description": "Label source URL.",
      -        "type": "string"
      -      }
      -    },
      -    "required": [
      -      "kind",
      -      "chapter",
      -      "label",
      -      "section",
      -      "sectionLabel",
      -      "reserved",
      -      "sourceUrl",
      -      "capturedAt",
      -      "labelSource",
      -      "scheduleUrl"
      -    ],
      -    "type": "object"
      -  },
      -  {
      -    "additionalProperties": false,
      -    "description": "One edition-pinned published quantity unit.",
      -    "properties": {
      -      "citation": {
      -        "description": "Official General Note citation.",
      -        "type": "string"
      -      },
      -      "kind": {
      -        "const": "unit",
      -        "description": "Published quantity-unit abbreviation.",
      -        "type": "string"
      -      },
      -      "meaning": {
      -        "description": "Published unit meaning.",
      -        "type": "string"
      -      },
      -      "sourceEdition": {
      -        "description": "Verification edition.",
      -        "type": "string"
      -      },
      -      "sourceUrl": {
      -        "description": "Edition-pinned official source.",
      -        "type": "string"
      -      },
      -      "symbol": {
      -        "description": "Exact abbreviation, preserving exponents.",
      -        "type": "string"
      -      }
      -    },
      -    "required": [
      -      "kind",
      -      "symbol",
      -      "meaning",
      -      "citation",
      -      "sourceUrl",
      -      "sourceEdition"
      -    ],
      -    "type": "object"
      -  },
      -  {
      -    "additionalProperties": {
      -      "$ref": "#/$defs/__schema0"
      -    },
      -    "description": "One published edition with every available metadata field.",
      -    "properties": {
      -      "date": {
      -        "description": "Published date source string.",
      -        "type": [
      -          "string",
      -          "null"
      -        ]
      -      },
      -      "description": {
      -        "description": "Published description.",
      -        "type": [
      -          "string",
      -          "null"
      -        ]
      -      },
      -      "kind": {
      -        "const": "release",
      -        "description": "Published edition record; no historical tariff lookup promise.",
      -        "type": "string"
      -      },
      -      "name": {
      -        "description": "Published release identifier.",
      -        "type": "string"
      -      },
      -      "releaseEndDate": {
      -        "description": "Published end-date source string.",
      -        "type": [
      -          "string",
      -          "null"
      -        ]
      -      },
      -      "releaseStartDate": {
      -        "description": "Published start-date source string.",
      -        "type": [
      -          "string",
      -          "null"
      -        ]
      -      },
      -      "sourceUrl": {
      -        "description": "Official edition metadata endpoint.",
      -        "type": "string"
      -      },
      -      "status": {
      -        "description": "Published status.",
      -        "type": [
      -          "string",
      -          "null"
      -        ]
      -      },
      -      "target": {
      -        "description": "Published target source string.",
      -        "type": [
      -          "string",
      -          "null"
      -        ]
      -      },
      -      "title": {
      -        "description": "Published title.",
      -        "type": [
      -          "string",
      -          "null"
      -        ]
      -      }
      -    },
      -    "required": [
      -      "kind",
      -      "name",
      -      "sourceUrl"
      -    ],
      -    "type": "object"
      -  }
      -]New value: +[
      +  {
      +    "additionalProperties": false,
      +    "description": "One accepted tariff identifier format.",
      +    "properties": {
      +      "digits": {
      +        "description": "Digit count.",
      +        "maximum": 9007199254740991,
      +        "minimum": -9007199254740991,
      +        "type": "integer"
      +      },
      +      "format": {
      +        "description": "Conventional dotted format.",
      +        "type": "string"
      +      },
      +      "kind": {
      +        "const": "identifier",
      +        "description": "Identifier explanation.",
      +        "type": "string"
      +      },
      +      "meaning": {
      +        "description": "Hierarchy, inheritance or evidence semantics.",
      +        "type": "string"
      +      },
      +      "name": {
      +        "description": "Identifier kind.",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "kind",
      +      "name",
      +      "digits",
      +      "format",
      +      "meaning"
      +    ],
      +    "type": "object"
      +  },
      +  {
      +    "additionalProperties": false,
      +    "description": "One edition-pinned program symbol; the page decoder carries its provenance.",
      +    "properties": {
      +      "countryListCoverage": {
      +        "const": "unknown",
      +        "description": "Country membership has not been independently verified.",
      +        "type": "string"
      +      },
      +      "kind": {
      +        "const": "program",
      +        "description": "Reviewed program symbol record.",
      +        "type": "string"
      +      },
      +      "name": {
      +        "description": "Reviewed program name.",
      +        "type": "string"
      +      },
      +      "symbol": {
      +        "description": "Exact SPI, preserving suffix punctuation.",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "kind",
      +      "symbol",
      +      "name",
      +      "countryListCoverage"
      +    ],
      +    "type": "object"
      +  },
      +  {
      +    "additionalProperties": false,
      +    "description": "One published chapter and its section navigation labels.",
      +    "properties": {
      +      "capturedAt": {
      +        "description": "Date the navigation labels were captured.",
      +        "type": "string"
      +      },
      +      "chapter": {
      +        "description": "Two-digit chapter number.",
      +        "type": "string"
      +      },
      +      "kind": {
      +        "const": "chapter",
      +        "description": "Published application navigation label.",
      +        "type": "string"
      +      },
      +      "label": {
      +        "description": "Published chapter title.",
      +        "type": "string"
      +      },
      +      "labelSource": {
      +        "const": "published_application_navigation",
      +        "description": "Label extraction provenance.",
      +        "type": "string"
      +      },
      +      "reserved": {
      +        "description": "Whether this chapter is reserved.",
      +        "type": "boolean"
      +      },
      +      "scheduleUrl": {
      +        "description": "Official tariff schedule.",
      +        "type": "string"
      +      },
      +      "section": {
      +        "description": "Published section identifier.",
      +        "type": "string"
      +      },
      +      "sectionLabel": {
      +        "description": "Published section title.",
      +        "type": "string"
      +      },
      +      "sourceUrl": {
      +        "description": "Label source URL.",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "kind",
      +      "chapter",
      +      "label",
      +      "section",
      +      "sectionLabel",
      +      "reserved",
      +      "sourceUrl",
      +      "capturedAt",
      +      "labelSource",
      +      "scheduleUrl"
      +    ],
      +    "type": "object"
      +  },
      +  {
      +    "additionalProperties": false,
      +    "description": "One edition-pinned published quantity unit; the page decoder carries its provenance.",
      +    "properties": {
      +      "kind": {
      +        "const": "unit",
      +        "description": "Published quantity-unit abbreviation.",
      +        "type": "string"
      +      },
      +      "meaning": {
      +        "description": "Published unit meaning.",
      +        "type": "string"
      +      },
      +      "symbol": {
      +        "description": "Exact abbreviation, preserving exponents.",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "kind",
      +      "symbol",
      +      "meaning"
      +    ],
      +    "type": "object"
      +  },
      +  {
      +    "additionalProperties": {
      +      "$ref": "#/$defs/__schema0"
      +    },
      +    "description": "One published edition with every available metadata field.",
      +    "properties": {
      +      "date": {
      +        "description": "Published date source string.",
      +        "type": [
      +          "string",
      +          "null"
      +        ]
      +      },
      +      "description": {
      +        "description": "Published description.",
      +        "type": [
      +          "string",
      +          "null"
      +        ]
      +      },
      +      "kind": {
      +        "const": "release",
      +        "description": "Published edition record; no historical tariff lookup promise.",
      +        "type": "string"
      +      },
      +      "name": {
      +        "description": "Published release identifier.",
      +        "type": "string"
      +      },
      +      "releaseEndDate": {
      +        "description": "Published end-date source string.",
      +        "type": [
      +          "string",
      +          "null"
      +        ]
      +      },
      +      "releaseStartDate": {
      +        "description": "Published start-date source string.",
      +        "type": [
      +          "string",
      +          "null"
      +        ]
      +      },
      +      "sourceUrl": {
      +        "description": "Official edition metadata endpoint.",
      +        "type": "string"
      +      },
      +      "status": {
      +        "description": "Published status.",
      +        "type": [
      +          "string",
      +          "null"
      +        ]
      +      },
      +      "target": {
      +        "description": "Published target source string.",
      +        "type": [
      +          "string",
      +          "null"
      +        ]
      +      },
      +      "title": {
      +        "description": "Published title.",
      +        "type": [
      +          "string",
      +          "null"
      +        ]
      +      }
      +    },
      +    "required": [
      +      "kind",
      +      "name",
      +      "sourceUrl"
      +    ],
      +    "type": "object"
      +  }
      +]
    • changedOutput schema / properties / notice / description
      Previous value: -"Actionable next call for this particular empty result."New value: +"Actionable next call for this particular empty result, followed by a disclosure when a requested limit above 100 was clamped."
    • removedOutput schema / properties / page / properties / budgetLimited
      Removed value: -{
      -  "description": "True when the complete reply byte budget reduced this page.",
      -  "type": "boolean"
      -}
    • changedOutput schema / properties / page / properties / effectiveLimit / description
      Previous value: -"Applied item ceiling after clamping to 100."New value: +"Requested limit after clamping to 100; every page but the last is full."
  2. First observed

TDQS

A3.7/5.0
Behavior4/5

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld), so the description is free to spend its words on caveats—and does: SPIs are edition-pinned, country membership is unknown absent verified lists, releases are publication metadata only. The one gap is that pagination is stated as a directive ('Follow nextCursor for all entries') without saying what happens at the end of a page.

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?

Four sentences, each carrying either a topic mapping, a scope exclusion, or an operational rule—no filler. The first sentence is a comma-spliced list that takes a second read to parse, which is the only structural weakness.

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

Completeness4/5

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

An output schema exists and annotations are rich, so the description only needs to supply the caveats structured fields cannot express, and it does. For a three-parameter read-only lookup this is nearly sufficient; only the explicit alternative-tool routing 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 all three parameters are already documented, including the enum of topics. The description adds little beyond restating the topic set and the cursor rule, which the schema's own cursor text already explains. Baseline 3 applies.

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

Purpose4/5

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

The verb 'List' plus the five enumerated reference tables (identifier formats, SPI, chapter/section labels, units, release metadata) maps directly onto the topic enum, so an agent can tell this is a static reference-table lookup rather than an HTS search. It stops short of naming a sibling, and the opening sentence is an unpunctuated enumeration whose subject is never stated, so the differentiator from usitc_search_hts is implied rather than asserted.

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

Usage Guidelines3/5

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

Two exclusions are given: program names are not decoded here (country membership is unresolvable), and release records do not enable historical tariff lookup. Those are genuine when-not signals, but the description never states positively when to reach for this tool versus usitc_search_hts or usitc_get_heading, leaving the routing to inference.

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.