Skip to main content
Glama
htsapi.dev MCP server

htsapi.dev MCP server

lookup_hts_code

Read-onlyIdempotent

Look up HTS tariff codes by chapter, heading, or 10-digit line to view legal text, subheadings, base and special rates, and related CBP rulings.

Instructions

The tariff schedule, one level at a time, the way a classifier reads it. No code: the 22 sections and their chapters, for goods no ruling covers. A chapter (82) lists its headings with their legal text; a heading (8205) lists its subheadings in words; a subheading or line gives its path from the heading (an "Other" line says what it is not), base rates with the special-rate programs named, the 10-digit lines under it and the newest current CBP rulings under it. A code no longer in the schedule falls back to the nearest level that is. What importers paid is a separate tool, importers_paid.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "lookup_hts_code"
  }
}

Input Schema

NameRequiredDescriptionDefault
codeNoAn HTS chapter, heading or code, 2 to 10 digits, dotted or not (82, 8205, 8205.51, 8205517500). Leave it out for the sections and chapters.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.0.0

TDQS

A4.1/5.0
Behavior4/5

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavior: a retired code falls back to the nearest level still in the schedule, an 'Other' line is described as a negative definition, and subheading responses include path-from-heading, base and special rates, 10-digit lines and the newest rulings. Return-shape detail overlaps the output schema, which slightly dilutes the added value.

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?

The description is dense but front-loaded: the resource and the level-by-level model come first, then per-level specifics, then the fallback and the sibling pointer. The telegraphic, fragment-heavy style ('a heading (8205) lists its subheadings in words') costs a little readability, but no sentence is padding.

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 single optional-parameter, read-only lookup with a full output schema and complete annotations, the description covers everything an agent needs: how to call it with and without a code, what each level returns, how invalid/retired codes behave, and which adjacent need belongs to another tool. Return-value detail is legitimately deferred to the output schema.

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% and the parameter description already spells out digit ranges, dotted/undotted formats and the null default. The description still adds meaning the schema does not: that the digit depth of the code selects which level's content comes back (chapter shows headings with legal text, heading shows subheadings in words, subheading shows path and rates), which is real guidance for choosing an argument value.

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 description conveys a specific resource (the HTS tariff schedule) and a specific navigation model ('one level at a time'), and it explicitly carves out what it is not by naming importers_paid for duty-paid data. What it lacks is an explicit verb framing the operation (lookup/retrieve), so the purpose is inferred from the level-by-level examples rather than stated outright.

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

Usage Guidelines4/5

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

It gives a concrete entry condition ('No code: the 22 sections and their chapters') and a scope exclusion ('for goods no ruling covers'), and it routes one adjacent need to a named sibling (importers_paid). Alternatives for the ruling-oriented lookups (rulings_under_code, get_ruling) are not named, so the guidance is clear but not exhaustive.

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