Documentation
Tools exposed by Tariff Code Finder and the limits that apply.
Connect
Server URL: https://tariff.tidybutton.com/mcp. Authentication is OAuth with dynamic client registration and an email sign-in code. Claude: Settings, Connectors, Add custom connector.
Tools
search_codes
Searches the official tariffs for a product description and returns candidate codes per market with the description path and, for the top candidates, duty rates.
- Inputs: description, markets (optional), candidates (optional, up to 8 per market)
- Limits: Counts one lookup when at least one candidate is found. Rates are read for the first 3 declarable UK and EU candidates. Keyword search: results are candidates, not a classification.
get_code
One tariff code in one market: description path, duty rates, units, footnotes, other measures, and the lines below it when it is a heading or subheading.
- Inputs: code (4, 6, 8 or 10 digits), market
- Limits: Counts one lookup. At most 40 lines below a code are listed.
compare_markets
One code across the US, UK and EU side by side: rates, VAT, units, notes and links.
- Inputs: code (6, 8 or 10 digits)
- Limits: Counts one lookup. National lines differ after the 6th digit; where an exact line is missing the 6-digit level is shown and flagged.
classify_list
Finds the top candidate code per market for a batch of product descriptions, from a list, a saved list, or a CSV file at a public URL (Pro).
- Inputs: descriptions, or list_name, or csv_url with column; offset (optional); markets (optional)
- Limits: Counts one lookup per description that gets a candidate. Up to 25 descriptions per call; larger sources continue with next_offset. CSV input needs Pro. Default markets US and UK.
save_list
Saves or extends a named list of products (description, optional reference and chosen code).
- Inputs: name, products, replace (optional)
- Limits: No lookup quota. Saved lists and products per list are limited by plan.
list_saved
Lists saved product lists, or returns the products of one list.
- Inputs: name (optional), offset (optional)
- Limits: No quota.
remove_list
Deletes a saved product list.
- Inputs: name
- Limits: No quota.
add_watch
Puts codes on a rate-change watch in chosen markets and records the current rates as the baseline.
- Inputs: codes (up to 5), markets (optional, default all three)
- Limits: Pro. Each code and market pair is one watch and counts one lookup. At most 100 watches.
list_watches
Lists watches with the code, market, last check and next scheduled check.
- Inputs: none
- Limits: No quota.
remove_watch
Removes a watch by its watch id.
- Inputs: watch_id
- Limits: No quota.
get_alerts
Recorded rate-change alerts, unseen first; marks the returned alerts as seen.
- Inputs: limit (optional), include_seen (optional)
- Limits: No quota.
account_status
Shows the account email, plan, usage and limits.
- Inputs: none
- Limits: none
activate_license
Binds a licence key to the account.
- Inputs: license_key (string)
- Limits: Key must belong to this product.
Plan limits
| Limit | Free | Pro |
|---|---|---|
| lookups | 30 | 3000 |
| saved lists | 3 | 50 |
| list_products | 25 | 500 |
| watches | 0 | 100 |
Network behaviour
Outbound requests use the user agent TidyButtonBot/1.0 (+https://tariff.tidybutton.com/bot), time out after 8 seconds and are blocked from private, loopback and link-local addresses.