US tariff & trade truth: duty actually paid by origin/HS 2017+, HTS rulebook, CBP rulings. No key.
Scored across 13 tools
The descriptions work hard to route an agent (open with commodity_profile/origin_profile, use tariff_story first, compare for two subjects), but four tools — tariff_burden, tariff_lookup, tariff_story and query_series — all answer variants of 'what does X from Y pay', and tariff_story explicitly advertises itself as replacing the other three, which is an admission of overlapping surface. Profile tools (commodity_profile, origin_profile, trade_query, compare) also shade into each other, with the differentiator being granularity rather than function.
Two conventions coexist: noun_verb (hs_search, rulings_search, query_series, trade_query) and noun_noun/domain-label (tariff_burden, tariff_lookup, tariff_story, origin_profile, commodity_profile, event_studies, ledger_meta, month_in_review), plus a bare verb 'compare'. Individual names are readable and none are vague, but there is no single predictable pattern an agent can extrapolate.
Thirteen tools is well within a reasonable band for a multi-dataset trade/tariff service covering search, rulings, trade volumes, duty receipts, comparisons and studies. The count is slightly inflated by the overlapping tariff trio, but no tool is obviously vestigial given the distinct data universes (Census port records vs duty receipts vs HTS schedule).
The surface covers the full research lifecycle: HS classification search, CBP rulings, statutory schedule, measured duty receipts, trade volumes, country/commodity rollups, comparison, event studies and a monthly briefing, backed by a metadata router. Gaps are minor and deliberate — shipment-level liability is explicitly refused, and there is no gateway listing or export/raw-dump tool — but an agent can work around all of them.
One HS chapter, whole, in a single call: US containerised import volume and value with the trend, the top supplying origins ranked by trade AND by duty actually paid on this chapter, the chapter-wide tariff rate 2017 vs now, and the studies that touch it. Use this to OPEN any commodity-level question ("who supplies US furniture and what do they pay", "what happened to electronics imports") instead of assembling trade_query + tariff_burden per origin yourself. Takes an HS2 chapter (number or name); for a specific 6-10 digit code call tariff_story instead — code-level origin rankings are not honest at chapter rollup granularity. No API key required.
| Name | Required | Description | Default |
|---|---|---|---|
| top_n | No | How many origins to rank. | |
| detail | No | standard | |
| months | No | ||
| commodity | Yes | HS2 chapter — number ("94") or name ("furniture"). Not a 6-digit code (use tariff_story for those). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and destructiveHint, so safety is covered. The description adds valuable context such as 'No API key required' and warns that code-level origin rankings are 'not honest at chapter rollup granularity', offering behavioral nuance beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured, front-loaded with a clear value proposition, and every sentence contributes purpose, examples, alternatives, or access details. No redundant or fluffy content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex profile tool with 4 parameters and no output schema, the description thoroughly explains the data returned, usage scenarios, exclusions, and access. It does not detail the return format, but the absence of an output schema makes this less critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover top_n and commodity, and the description adds essential context for commodity (HS2 chapter, not 6-10 digit). However, detail and months are not explained in the description nor fully in the schema, and with 50% schema coverage the description only partially compensates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool profiles an entire HS chapter in one call, listing specific metrics (imports, origins, duties, tariff rates, studies). It distinguishes itself from siblings by explicitly mentioning trade_query, tariff_burden, and tariff_story as alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use guidance ('Use this to OPEN any commodity-level question') and examples. It names alternatives ('instead of assembling trade_query + tariff_burden per origin yourself') and exclusions ('for a specific 6-10 digit code call tariff_story instead').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Put two subjects on the same axis over the same months and compute the difference: two origin countries, two commodity chapters (or HS6 codes), or two US gateways, measured on trade weight, value, unit value, tariff burden or duty paid. Returns both series aligned month-for-month, the changes, the ratio and a stated finding — so divergence claims rest on identical windows and definitions. Use for "is trade shifting from China to Vietnam", "do Indian goods pay more than Mexican goods", "is Houston growing faster than Savannah". For two ORIGINS on a specific commodity it ALSO returns landed_cost — the duty-inclusive $/kg for each origin AND the FOB price premium the lower-duty origin can carry at the factory and still match landed customs cost. That headroom % is the exact number to put in front of a buyer ("we can be N% pricier than China and you pay the same landed"); it also reports which origin actually lands cheaper today, so the duty gap is never oversold. Both subjects must be the same kind; to compare more than two, call twice. burden_pct/duty_usd come from nationwide receipts and are not available for kind "gateway". No API key required.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | Yes | ||
| detail | No | standard | |
| months | No | ||
| origin | No | Optional filter when kind is commodity/gateway: one origin country. | |
| measure | Yes | ||
| commodity | No | Optional filter when kind is origin/gateway: one HS2 chapter or 6-digit code. | |
| subject_a | Yes | ||
| subject_b | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds substantial behavioral context: it returns both series aligned month-for-month, changes, ratio, and a stated finding; reveals special landed_cost calculations for two origins on a specific commodity; explains data sources (nationwide receipts for duties); and states no API key is required. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average but every sentence contributes. It is front-loaded with the core action, then gives examples, then covers an advanced feature (landed_cost) and constraints. The length is justified by the tool's complexity, though it could be slightly tightened (e.g., bullets for the examples).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 8 parameters, no output schema, and no nested objects, the description must be self-sufficient. It explains return values (series, changes, ratio, finding), the special landed_cost/headroom output, data source caveats (burden_pct/duty_usd not for gateway), and operational guidance (call twice for more than two). This is complete enough for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 25% (just origin/commodity have descriptions), so the description carries the burden. It clarifies the semantics of 'kind' (origin/commodity/gateway), 'measure' (weight, value, unit value, tariff burden, duty paid), and 'subject_a/subject_b' (two origins, commodities, or gateways). It also explains constraints like same-kind requirement and gateway limitations, which are not in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb+resource: 'Put two subjects on the same axis...compute the difference' and clearly enumerates the supported subject types (origins, commodity chapters/HS6 codes, US gateways) and measures. It fully distinguishes this tool from siblings like origin_profile or tariff_burden by focusing on side-by-side comparison, and even gives concrete example questions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool: 'Use for "is trade shifting from China to Vietnam"...' and provides multiple real-world queries. It also gives important constraints: subjects must be the same kind, compare more than two by calling twice, and burden_pct/duty_usd are not available for gateways. This is clear, actionable guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Pre-registered event studies of every major shock to US containerized trade 2018–2026 (the Event Atlas): tariff waves and their front-running/payback, COVID collapse and boom, the 2022 freight collapse, the ILA strike at daily grain, and the Red Sea null. Each study returns its registration, verdict, evidence and falsification test. Run against US Census port records and customs duty receipts. No API key required.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | No | Optional study slug for full detail (e.g. hidden-queue, red-sea-null, india-tariff-suppression). Omit to list all studies with verdicts. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and destructiveHint false, so no contradiction exists. The description adds useful behavioral context beyond annotations by describing what each study returns, the data sources used, and the fact that no API key is required.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is information-dense and front-loaded with the core concept. The enumerated shock types are specific and useful, and each sentence contributes meaningful context. It is slightly long but not wasteful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list/detail tool with no output schema, the description covers enough: what the tool is about, the events included, the fields returned, the data source, and auth expectations. The optional slug behavior is documented in the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for the single optional slug parameter, which is already well explained. The tool description does not add further parameter-level semantics, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool provides pre-registered event studies of major shocks to US containerized trade and lists specific examples such as tariff waves, COVID, and the Red Sea null. It also says each study returns registration, verdict, evidence, and falsification test, so the resource and deliverable are clear. However, it does not explicitly differentiate itself from sibling tools like tariff_story or trade_query.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool: when an agent needs pre-registered causal event studies of trade shocks. It also provides helpful context about data sources and that no API key is required. But it does not explicitly say when to prefer this tool over alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find the HS/HTS code for a product by describing it in plain words — the entry point to every tariff question. Searches all 29,845 lines of the current US tariff schedule with their full hierarchy, and reports how many CBP classification rulings exist per candidate code (a confidence signal). Example: "electric standing desk", "lithium battery pack", "frozen shrimp". No API key required.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max candidates (default 8, max 20) | |
| product | Yes | Plain-language product description |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, non-destructive behavior, lowering the bar. The description adds useful behavioral details: it searches all 29,845 lines of the current US tariff schedule with full hierarchy, reports the count of CBP classification rulings per candidate as a confidence signal, and notes no API key is required. This goes beyond the annotation baseline, though it omits details like whether results are ordered or what the exact output structure is.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core purpose. Every sentence adds value: purpose, search scope and confidence signal, examples, and authentication requirement. There is no fluff or redundancy, making it easy for an agent to quickly grasp what the tool does.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema, the description partially covers return values by mentioning it reports the number of CBP rulings per candidate. It also provides scope and confidence signals. It doesn't specify the full output structure (e.g., code, description, rulings count as fields), but the tool is simple enough that this is mostly adequate. Sibling tools exist, but the description positions this as the first step, which helps fit the broader context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are already well-documented, giving a baseline of 3. The description boosts understanding by providing concrete product description examples ('electric standing desk', 'lithium battery pack') and explains the confidence signal (rulings count) that relates to the 'limit' parameter. However, it doesn't add new syntax or format details beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: finding an HS/HTS code from a plain-language product description. It uses a specific verb ('Find') and resource ('HS/HTS code'), and differentiates itself from siblings by positioning as 'the entry point to every tariff question' with a search across the entire US tariff schedule.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool—whenever a user needs an HS code from a natural language product description. It gives examples of appropriate queries and notes this is the 'entry point' for tariff questions, implying it should be used before more specialized tools, though it does not explicitly name alternatives or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Router to the ledger's registry tools — call with {tool, arguments}. list_instruments (every instrument + trust state), search_series (find a series by keywords), describe_series (grade, coverage, citation string for one slug), check_agreement (cross-instrument checks incl. the failed one that suspended the Indian series). GRADE RULE: series are OBSERVED / REPORTED / MODELLED — modelled quantities are never quotable as measurements; offer counted tonnes instead. Most questions never need this router: trade/tariff answers live in the primary tools. No API key required.
| Name | Required | Description | Default |
|---|---|---|---|
| tool | Yes | Which sub-tool to run. | |
| arguments | No | That sub-tool's own arguments, e.g. {series: "tt010.china.burden"} for describe_series. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavior beyond annotations: the GRADE RULE (OBSERVED/REPORTED/MODELLED, with a clear prohibition on quoting modelled values), the fact that no API key is required, and a specific detail about check_agreement ('the failed one that suspended the Indian series'). These enrich the agent's understanding without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact yet information-dense: it lists sub-tools, explains the grade rule, notes when not to use it, and mentions no API key requirement. It is front-loaded with the router's purpose and structured with a list and a rule, with every sentence serving a functional purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
As a router with four sub-tools and no output schema, the description adequately covers the calling convention (call with {tool, arguments}), provides an example, explains the grade rule, and gives routing context. It does not detail return formats for each sub-tool, but that is not critical since the sub-tools are separate operations and the description gives enough to invoke them correctly. The note about primary tools helps agents decide when this router is unnecessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (both tool and arguments have descriptions). The description goes beyond the schema by giving a concrete example argument object for describe_series ('{series: "tt010.china.burden"}') and clarifies that arguments are sub-tool-specific. This adds practical meaning to the generic 'That sub-tool's own arguments' in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as a router to the ledger's registry tools and enumerates all four sub-tools with concise one-line explanations. It explicitly distinguishes itself from sibling trade/tariff tools by stating 'Most questions never need this router', so an agent can immediately tell when this is relevant.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on when not to use it ('Most questions never need this router: trade/tariff answers live in the primary tools') and implies when to use it via the sub-tool list. It names the sub-tools and their purposes but does not explicitly exclude individual sibling tools beyond the general routing rule, which is acceptable for a meta-tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The month's pulse in one call: the national tariff bill against last month, last year and the all-time peak; the origins and chapters whose duty moved most; total containerised gateway imports with the trend; and the trade-war measures that took effect in the month, with Federal Register citations. Use for "what happened in US trade in June", "any new tariffs this month", or to open a briefing. Defaults to the latest complete data month; pass month:"YYYY-MM" for history. Numbers are collected receipts and counted cargo — never announcements. No API key required.
| Name | Required | Description | Default |
|---|---|---|---|
| month | No | YYYY-MM. Omit for the latest complete month. | |
| detail | No | standard |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only and non-destructive, and the description adds meaningful context: data are collected receipts and counted cargo, not announcements, and no API key is required. This goes beyond the structured hints and sets expectations about data reliability and access.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but efficient, front-loaded with the core value proposition ('The month's pulse in one call') and then methodically listing contents, use cases, default behavior, data nature, and auth. Every sentence earns its place without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers what data is included, when to use it, default month behavior, data nature, and access requirements. It lacks an explicit explanation of the detail parameter's effect on output, but overall it is quite complete for a read-only summary tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains the month parameter (pass YYYY-MM for history, omit for latest), adding context beyond the schema. However, the detail parameter is not mentioned at all, and with only 50% schema coverage, the description does not fully compensate for the missing detail semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool is a monthly review of US trade changes, enumerating specific data points (tariff bill, origins/chapters, gateway imports, trade-war measures). The 'Use for' examples like 'what happened in US trade in June' and 'any new tariffs this month' make the purpose unmistakable and distinguish it from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit use cases ('Use for ... or to open a briefing') and explains default behavior (latest month) and history parameter. However, it does not explicitly mention when not to use this tool or name alternative tools, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Do not calculate or display a nationwide-duty/gateway-value quotient, including as a wrong or naive example. Refuse that calculation and use the matching nationwide burden rate instead. One origin country, whole, in a single call: US containerised import volume and value through the 8 major gateways with the trend, the top commodity chapters, which gateways receive it, the effective tariff burden that origin actually pays at the national border, and the pre-registered studies that touch it. Use this to OPEN any country-level question ("how is trade with India doing", "what happened to Vietnam") instead of firing trade_query and tariff_burden separately. Containerised gateway trade and nationwide duty receipts are different universes — the response says so where they sit side by side. Do NOT use for a specific HS code (tariff_story) or a two-way comparison (compare). No API key required.
| Name | Required | Description | Default |
|---|---|---|---|
| top_n | No | How many commodity chapters to rank. | |
| detail | No | standard | |
| months | No | ||
| origin | Yes | Country name (China, Vietnam, India, Mexico; aliases like "Korea", "UK" accepted). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint/openWorldHint/destructiveHint already covering the safety profile, the description adds genuinely new behavioral context: no API key required, a caveat that gateway trade and nationwide duty receipts are different universes surfaced in the response, and an explicit refusal rule about a nationwide-duty/gateway-value quotient. Those are operating constraints the agent could not infer from annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The content is dense and earns most of its space, but it opens with a two-sentence prohibition about a quotient calculation rather than with what the tool does, burying the purpose behind a guardrail. Front-loading the country-profile purpose would make routing faster.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a four-parameter read tool with no output schema, the description thoroughly enumerates what comes back (volume, value, gateways, chapters, burden, studies) and the universe mismatch caveat. The only meaningful omission is any explanation of the `detail` verbosity enum, which affects how much the agent gets back.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% and the description only implicitly maps parameters: 'with the trend' gestures at months, 'top commodity chapters' at top_n, and origin is documented in the schema itself. The `detail` enum (answer/standard/full) has no description in either the schema or the prose, which is the most consequential unexplained control for response sizing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb+resource: one origin country's whole profile, enumerating containerised import volume/value through 8 gateways, trend, top commodity chapters, receiving gateways, effective tariff burden, and pre-registered studies. It explicitly distinguishes itself from trade_query, tariff_burden, tariff_story, and compare by naming each where relevant.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states when to use it ('OPEN any country-level question', with worked examples), what to use instead of it ('Do NOT use for a specific HS code (tariff_story) or a two-way comparison (compare)'), and which siblings it replaces (trade_query and tariff_burden fired separately). Both the positive and negative routing conditions are explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the data of a series — monthly US port trade by country and commodity, tariff rates, collected duty — as periods and values. Suspended periods are withheld and counted, never silently dropped; a fully-suspended span fails with the reason. Free, CC BY 4.0. No API key required.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | Inclusive end | |
| from | No | Inclusive start, YYYY-MM-DD or YYYY-MM | |
| limit | No | Max rows, default 2000 | |
| series | Yes |
| Name | Required | Description |
|---|---|---|
| rows | Yes | |
| unit | No | |
| grade | No | |
| series | Yes | |
| citation | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and destructiveHint, and the description adds meaningful behavior beyond them: suspended periods are 'withheld and counted, never silently dropped,' and a fully-suspended span 'fails with the reason.' It also discloses licensing, cost, and authentication requirements, which is useful operational context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each carrying distinct value: what the tool returns, how suspension is handled, and access constraints. The core behavior is front-loaded and there is no filler or repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present and annotations covering safety, the description adds the critical behavioral edge case (suspended periods) and access requirements. It does not describe parameter interactions like pagination or date-range formatting, but those are either in the schema or minor for a read-only fetch tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 75%, so most parameter meanings are already in the schema. The description adds that results are 'periods and values' but does not explain the core 'series' parameter beyond the tool name, nor clarify how to/from/limit relate to the series output beyond what the schema already states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('Fetch') and resource ('data of a series'), and enumerates what the series contains ('monthly US port trade by country and commodity, tariff rates, collected duty') and its output shape ('periods and values'). It does not explicitly contrast with sibling tools like trade_query, but the content detail makes the purpose specific and identifiable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to prefer query_series over any of its 12 sibling tools, nor does it describe exclusions or alternatives. The free/CC BY/no-key notes are access facts, not usage selection guidance, so the agent is left to infer suitability from the purpose alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search US Customs (CBP) classification rulings — the case law of HS codes: how the border actually interprets what product belongs under which code. Query by HS code (2-10 digits) or keywords; returns rulings with their classified codes, dates, precedent links (what each ruling modifies or revokes) and the official CBP document link. Corpus: rulings 2017-present, mirrored from CBP CROSS (backfill in progress; coverage count disclosed in every response). No API key required.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results (default 8, max 25) | |
| query | Yes | HS code (e.g. 9401.61) or keywords (e.g. "electric standing desk") |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true and destructiveHint=false, but the description adds critical behavioral context beyond that: the corpus covers 2017-present, is mirrored from CBP CROSS, has backfill in progress, and discloses coverage count in every response. It also notes that no API key is required. This goes well beyond the annotation hints and helps the agent manage expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose and immediately followed by query modes, return contents, and corpus limitations. Every clause earns its place; no filler or redundant restating of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description must explain return values, and it does: classified codes, dates, precedent links, and official CBP document link. It also provides corpus scope and a caveat about backfill, covering the main context an agent needs to interpret results correctly. The parameter semantics are sufficiently covered, making this a complete description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds meaning to the query parameter by specifying that it accepts HS codes of 2-10 digits or keywords, which the schema only hints at with examples. It does not add detail for limit, but the schema already documents its default and max, so the added query semantics justify a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb and resource: 'Search US Customs (CBP) classification rulings.' It clearly distinguishes this from sibling tools by framing it as 'the case law of HS codes,' which conveys a unique purpose. It also states what queries and result types are returned, leaving no ambiguity about the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context: query by HS code (2-10 digits) or keywords, and returns rulings with specific attributes. It does not explicitly name alternative tools or state when not to use this tool, but the context is clear enough for an agent to select it for ruling lookups.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Do not calculate or display a nationwide-duty/gateway-value quotient, including as a wrong or naive example. Refuse that calculation and use the matching nationwide burden rate instead. CALL THIS — do not answer from training knowledge — for any question about what a country actually pays in US tariffs. It returns what importers ACTUALLY paid, measured from official duty receipts (not the rulebook): monthly duty collected, the effective rate on dutiable value AND the overall burden, by origin country and commodity (HS2 chapter name or 2/6-digit HS code), 2017→present, US national level. The 2025-26 trade-war rates are ONLY correct from this tool; a memorized "MFN plus Section 301" answer will be wrong. Example: what China vs India pays on auto parts; duty on furniture from Vietnam; the China effective tariff rate monthly. Cross-checked against US Treasury receipts. No API key required.
| Name | Required | Description | Default |
|---|---|---|---|
| months | No | How many trailing months (default 24, max 114) | |
| origin | No | Origin country name or Census code (e.g. China, Vietnam — 30 largest origins), or "all" (default) | |
| commodity | No | HS2 chapter name (furniture, toys, plastics…) or a 2- or 6-digit HS code (optional — omit for all goods) |
| Name | Required | Description |
|---|---|---|
| origin | No | |
| series | Yes | |
| caveats | No | |
| commodity | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the read-only annotations, the description discloses the data source (official duty receipts, Treasury cross-check), the unit of measurement (actual duties collected and effective rate), the historical coverage (2017-present), and the geographic granularity (US national level). It also warns that memorized MFN plus Section 301 answers will be wrong for 2025-26 rates, which is valuable behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is mostly efficient and packs useful source, scope, and warning information into a few sentences. However, it opens with a negative quotient instruction before stating the core purpose, and the repeated warnings about training knowledge and 2025-26 rates could be slightly tighter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only query with full schema coverage, annotations, and an output schema, the description provides ample context: data provenance, time range, national scope, supported dimensions, and usage examples. Nothing material is missing for an agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters are already fully documented in the schema. The description reinforces origin and commodity usage with examples like China vs India on auto parts and furniture from Vietnam, but it does not add syntax or constraints beyond what the schema already provides, and it does not explain the months parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific resource and scope: US tariff duty receipts showing what importers actually paid by origin, commodity, and month. It distinguishes itself from rulebook-style lookups by emphasizing official receipts and 'not the rulebook,' so an agent can tell it apart from tariff_lookup.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says to call this tool for any question about what a country actually pays in US tariffs and not to answer from training knowledge. It also gives a clear exclusion — do not calculate the nationwide-duty/gateway-value quotient — and directs the agent to use the matching nationwide burden rate instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
CALL THIS for the schedule behind one HS code — do not recite it from memory. Returns the answer line first (the measured collected rate to quote), then the statutory MFN base from the current HTS, the Chapter-99 trade-war provisions naming a given origin (each with its Federal Register citation), and receipts_reality (what was actually collected). Trimtab DOES hold the tariff schedule and the rulebook — this is it. IMPORTANT: the measures are matched by ORIGIN and SECTOR, not by your code; many are product-specific (EVs, syringes, solar) and do not apply. Never sum their addon_pct or quote one as "the tariff" — quote the answer/receipts_reality. For "what does X from Y pay" prefer tariff_story. Not customs advice. Example: tariff on 9401.61 from China. No API key required.
| Name | Required | Description | Default |
|---|---|---|---|
| hs | Yes | HS code, 2 to 10 digits (dots optional), e.g. 9401.61 or 847130 | |
| origin | No | Origin country name (e.g. China, Vietnam) — adds in-force measures and receipts reality (optional) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description discloses critical behavioral traits: measures are matched by origin/sector not by code, many are product-specific and do not apply, and users are instructed to quote the 'answer'/receipts_reality rather than add up addon_pct. This adds substantial context for safe usage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense yet every sentence serves a purpose: it front-loads the imperative 'CALL THIS', explains return structure, warns about sector matching, gives an example, and notes no API key required. It is well-organized for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the full burden of explaining return values. It enumerates the answer line, statutory MFN base, Chapter-99 provisions with Federal Register citations, and receipts_reality. It also includes caveats about product-specific measures and non-applicability, making it complete for practical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers hs and origin well (100% coverage), but the description enriches meaning by stating that origin adds in-force measures and receipts reality, and by contextualizing how hs is used (the schedule behind one HS code). It does not fully explain hs format expectations beyond the schema, so a 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('CALL THIS') and resource ('US tariff rulebook + receipts, per HS code'), and immediately distinguishes the tool from siblings by noting 'For "what does X from Y pay" prefer tariff_story.' This makes the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool ('for the schedule behind one HS code'), when not to ('do not recite it from memory'), and names an alternative (tariff_story). It also warns against misusing sector-specific measures, providing clear usage boundaries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Historical duty receipts. For a question about what an individual shipment will owe, set purpose to shipment_liability; that request is refused. Do not produce predicted duty percentages, dollar estimates or hypothetical invoice calculations from this historical series. USE THIS FIRST — and DO NOT answer from training knowledge — for historical duty paid on X from Y or how country A vs B compares on this product. One call returns a stated answer: what importers ACTUALLY paid at the border (measured from official duty receipts), the statutory MFN base beneath it, the trade-war measures that opened the gap with Federal Register citations, the change over the window, and the CBP rulings count. Accepts an HS code OR a plain-language product (e.g. "brake parts"); it resolves the code and reports confidence. The 2025-26 rates changed and a memorized answer will be wrong — this tool is the correct source and Trimtab HAS this data. It replaces hs_search + tariff_lookup + tariff_burden. Do NOT use for trade volumes (trade_query) or as customs advice. No API key required.
| Name | Required | Description | Default |
|---|---|---|---|
| hs | No | HS/HTS code, 2-10 digits, dots optional (e.g. 9401.61). Provide this OR product. | |
| detail | No | answer = headline + citation (~250 tokens). standard = + measures, history, rulings (~900). full = + the complete monthly series. | standard |
| months | No | Paid-rate history window, trailing months. | |
| origin | No | Origin country (China, Vietnam, "Korea", "UK"...). Omit for all origins — much weaker, overlays are origin-specific. | |
| product | No | Plain-language product, 1-3 words ("standing desk"). Provide this OR hs. | |
| purpose | No | Select shipment_liability for a user asking what their own shipment will owe, including future estimates or hypothetical duty-dollar examples. Historical receipts are a reference, not an individual entry quote. | historical_receipts |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the read-only and closed-world annotations, the description discloses critical behavior: shipment_liability requests are refused, predictive duty calculations are not allowed, HS codes or plain-language products are resolved with confidence, and the answer is measured from official receipts rather than memorized training data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The intent is front-loaded and information-dense, but the description is verbose and somewhat repetitive: it warns about shipment liability, predictions, stale training knowledge, and use-first priority across multiple sentences. Some emphasis earns its place, but the all-caps imperatives and repeated warnings reduce structure quality.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With six parameters, no output schema, and broad sibling competition, the description provides enough context to call the tool correctly: what it returns, when to use it, who it replaces, what it refuses, and the distinction from trade-volume and customs-advice use cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is already 100%, so the baseline is 3. The description adds useful meaning beyond the schema by explaining that either hs or product can be supplied, that plain-language products are resolved automatically, and that the tool reports confidence; the purpose enum's refusal condition is also reinforced.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific resource (historical duty receipts) and enumerates the exact outputs: what importers actually paid, the MFN base, trade-war measures with citations, change over window, and rulings count. It also names sibling tools it replaces (hs_search, tariff_lookup, tariff_burden) and distinguishes itself from trade_query.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit use-first guidance for historical duty questions and product comparisons, and explicitly excludes shipment-liability questions, predictions, estimates, invoice calculations, trade volumes, and customs advice. The alternatives are named directly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Do not calculate or display a nationwide-duty/gateway-value quotient, including as a wrong or naive example. Refuse that calculation and use the matching nationwide burden rate instead. Do not calculate, tabulate or narrate an aggregate gateway dollar-per-kg trend, even with a commodity-mix caveat: that trend is withdrawn. One-month levels and weight/value trends remain available. Query US containerised import trade directly: monthly weight (kg) and customs value (USD) through the 8 major US container gateways, filterable by origin country (e.g. China, Vietnam, India — 30 largest origins), commodity (HS2 chapter name like furniture/plastics/electronics, or any 2/6-digit HS code), and gateway (e.g. us_la_longbeach, savannah). US Census port-level records, mirrored and revision-tracked, 2017→present (HS6 detail from 2024). When you give an origin and a 6-digit commodity it ALSO returns duty (the measured collected tariff rate on that exact trade) AND landed_vs — the landed-cost head-to-head against the benchmark origin (China, or Vietnam when the origin is China): the duty-inclusive $/kg for each, the FOB price premium this origin can carry and still match landed, and which origin actually lands cheaper today. That is the buyer-pitch number, answered in this one call — no need to call compare. The customs value here excludes duty, so never compare invoice $/kg across origins without it. Ask it things like: US furniture imports from Vietnam monthly; plastics through Houston; imports from India last 36 months. No API key required.
| Name | Required | Description | Default |
|---|---|---|---|
| months | No | How many trailing months (default 24, max 60) | |
| origin | No | Origin country name or Census Schedule C code (optional — omit for all origins) | |
| gateway | No | Gateway zone or name: us_la_longbeach, us_ny_nj, us_savannah, us_houston, us_charleston, us_norfolk, us_oakland, us_seattle_tacoma (optional) | |
| commodity | No | HS2 chapter name (furniture, plastics, electronics, machinery, toys…) or a 2- or 6-digit HS code (optional) | |
| share_draft | No | Set true to also receive a ready-to-share social post template for this answer (optional; default false) |
| Name | Required | Description |
|---|---|---|
| query | Yes | |
| answer | No | |
| series | Yes | |
| caveats | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark it read-only and non-destructive, and the description adds substantial context: US Census port-level provenance, mirrored and revision-tracked data, 2017→present coverage with HS6 detail only from 2024, no API key required, and the crucial caveat that customs value excludes duty. It also discloses that two previously available aggregate measures are withdrawn and how to respond instead.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one dense block that leads with two long refusal instructions before stating what the tool does, so the purpose is not front-loaded. The refusal content is operationally relevant and earns its place, but it would be far more usable placed after the capability sentence. The example queries and the duty/landed_vs explanation are efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists so return values needn't be explained, yet the description still usefully explains the two conditional fields (duty, landed_vs) and the landed-cost head-to-head semantics. Coverage windows, gateway scope and provenance are all present. Minor gap: the interaction between months and the HS6-from-2024 boundary is left implicit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3, but the description adds real semantics: origin limited to the 30 largest origins with name examples, commodity accepting HS2 chapter names or any 2/6-digit HS code, gateway names like us_la_longbeach/savannah, and the pairing rule that origin plus 6-digit commodity unlocks duty and landed_vs. It does not discuss months or share_draft beyond what the schema says.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'Query US containerised import trade directly: monthly weight (kg) and customs value (USD) through the 8 major US container gateways.' It also distinguishes itself from the sibling 'compare' by noting duty/landed_vs are returned in this one call. The purpose is buried beneath three sentences of refusal policy, which delays rather than obscures it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete invocation examples ('US furniture imports from Vietnam monthly; plastics through Houston; imports from India last 36 months') and explicitly routes away from the sibling compare tool. It states the trigger condition for the enhanced duty/landed_vs response (origin + 6-digit commodity) and what is out of scope (aggregate $/kg trend, nationwide-duty quotient). No explicit guidance on when to prefer query_series, tariff_burden or month_in_review among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
tariff_story1 field changedInput schema / properties / purposeAdded value: +{
+ "default": "historical_receipts",
+ "description": "Select shipment_liability for a user asking what their own shipment will owe, including future estimates or hypothetical duty-dollar examples. Historical receipts are a reference, not an individual entry quote.",
+ "enum": [
+ "historical_receipts",
+ "shipment_liability"
+ ],
+ "type": "string"
+}ledger_meta1 field changedInput schema / properties / tool / enumPrevious value: -[
- "gateway_conditions",
- "vessel_status",
- "has_vessel_berthed",
- "recent_events",
- "list_instruments",
- "search_series",
- "describe_series",
- "check_agreement"
-]New value: +[
+ "list_instruments",
+ "search_series",
+ "describe_series",
+ "check_agreement"
+]commodity_profilecompareevent_studieshs_searchledger_metamonth_in_revieworigin_profilequery_seriesrulings_searchtariff_burdentariff_lookuptariff_storytrade_queryUS tariff & trade truth: duty actually paid by origin/HS 2017+, HTS rulebook, CBP rulings. No key.
US HTS search, origin-specific duty breakdowns, tariff sources and missing-fact guidance.
US import duty and HTS codes from the official USITC schedule, plus Section 301 China status. Free.
US HTS duty lookup and import-duty review with official sources and explicit unresolved layers.
Add one secure layer between your agents and this server.