US tariff & trade truth: duty actually paid by origin/HS 2017+, HTS rulebook, CBP rulings. No key.
Scored across 13 tools
Several tools have overlapping missions: tariff_story explicitly says it replaces hs_search, tariff_lookup, and tariff_burden, yet those three remain separate first-class tools; compare and trade_query both return landed-cost head-to-heads for origin comparisons. The long descriptions help, but an agent must choose among multiple 'CALL THIS' tariff tools with genuinely fuzzy boundaries.
Names fall into families (entity_profile, *_search, tariff_*) but no single verb_noun convention: compare is a bare verb, event_studies and ledger_meta are noun phrases, and query_series vs trade_query mix verb-first and noun-first forms. Still, most names are readable and semantically suggestive, so it is not chaotic.
13 tools is a reasonable, well-scoped number for a comprehensive trade/tariff data server and stays inside the 3-15 sweet spot. It would tighten if tariff_story's explicit replacement of three other tools means those tools are redundant, but the count itself is not excessive.
The surface covers the full read-only workflow: plain-language HS lookup, specific code lookups, statutory and collected-duty views, rulings, origin and commodity profiles, monthly gateways/volumes, comparisons, raw series, monthly reviews, and event studies. There are no obvious dead ends for tariff or trade research, and mutation tools are not part of the server's purpose.
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.
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?
Annotations already mark readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable context: the distinction between containerised gateway trade and nationwide duty receipts, noting the response itself flags this, and explicitly states 'No API key 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?
Four sentences, each carrying distinct information: function, usage direction, data-caveat, and attribution. It is dense but not bloated. Slightly longer than the ideal two-sentence example, but no redundant filler.
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?
No output schema, but the description enumerates all key response components (gateways, trend, commodity chapters, tariff burden, studies) and provides usage context, exclusions, and a data interpretation caveat. For a read-only profile tool with minimal parameters, this is sufficiently complete.
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 50% (origin and top_n have descriptions; detail and months do not). The description indirectly refers to top_n via 'top commodity chapters' and months via 'trend', but does not clarify the 'detail' enum values or default behavior. Some added semantics, but incomplete for two parameters.
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 returns a comprehensive country-level profile: US containerised import volume and value through major gateways, trend, top commodity chapters, effective tariff burden, and related studies. It explicitly differentiates from siblings by naming trade_query, tariff_burden, tariff_story, and compare as alternatives to avoid.
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 country-level question... instead of firing trade_query and tariff_burden separately.' Also gives clear exclusions: 'Do NOT use for a specific HS code (tariff_story) or a two-way comparison (compare).' This goes beyond implied usage.
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.
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 readOnlyHint annotation, the description discloses that data is sourced from actual duty receipts (not the rulebook), covers 2017-present, is US national level, and is cross-checked against US Treasury receipts. It also notes 'No API key required.' These details add significant context about what the tool returns and how it behaves.
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 a single paragraph but effectively front-loaded with a strong 'CALL THIS' imperative and then packed with key details. Each sentence contributes to understanding, though the final 'No API key required' is a minor extra. It is efficient but not as lean as a two-sentence description.
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 the tool's complexity (3 optional parameters, an output schema exists), the description fully covers the return values (monthly duty, effective rate, overall burden), the level of aggregation (origin, commodity, time range, national level), and the usage context. It leaves no major gaps for an AI agent to invoke 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?
The input schema already provides 100% coverage with descriptions for all three parameters, including acceptable formats (Census code, HS2 chapter name). The description adds little beyond examples that combine parameters (e.g., 'China vs India pays on auto parts'), but does not introduce new semantics or constraints. Baseline 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 its purpose: returning actual US tariff receipts paid, measured from official duty receipts. It distinguishes itself from rulebook-based tools and training knowledge, and gives explicit examples of the kind of questions it answers (e.g., 'what China vs India pays on auto parts'). The verb+resource is specific and unambiguous.
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 begins with 'CALL THIS' and explicitly warns not to answer from training knowledge, marking a clear when-to-use signal. It further states that 2025-26 trade-war rates are ONLY correct from this tool, providing a strong exclusion for memorized answers. Examples of queries reinforce the intended scenarios.
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.
USE THIS FIRST — and DO NOT answer from training knowledge — for ANY "what is the tariff on X from Y" or "how does country A vs B compare on this product" question. 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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only and non-destructive. The description adds meaningful behavioral context: it uses official duty receipts, reports confidence on code resolution, includes Federal Register citations, and notes the 2025-26 rate changes. While it doesn't disclose edge-case behavior (e.g., invalid HS code handling), it is quite transparent given the read-only nature.
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 well-structured, front-loaded with 'USE THIS FIRST.' Every sentence adds value, though there is slight redundancy between 'USE THIS FIRST' and the later statement about 2025-26 rate changes. It could be tightened without losing meaning.
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 compensates by enumerating the return components (paid rate, MFN base, measures, citations, rulings count). It covers inputs, outputs, alternatives, exclusions, and data freshness. It lacks error-handling details and concrete output formatting examples, but is largely complete for a query 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 input schema covers all 5 parameters with detailed descriptions (HS/product OR relationship, defaults, enums). The description adds minimal extra value beyond schema, mainly re-emphasizing the HS-or-product duality and adding that it resolves the code and reports confidence. Since schema coverage is 100%, a 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 states a clear, specific purpose: answering tariff questions with a single call that returns paid rates, statutory MFN base, trade-war measures, and citations. It distinguishes from siblings by explicitly replacing hs_search, tariff_lookup, and tariff_burden, and by excluding trade volumes (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?
Provides explicit when-to-use guidance ('USE THIS FIRST', 'ANY ... question'), alternatives ('It replaces hs_search + tariff_lookup + tariff_burden'), and exclusions ('Do NOT use for trade volumes (trade_query) or as customs advice'). Also warns against training knowledge, reinforcing when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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?
Beyond the annotations (readOnlyHint=true, destructiveHint=false), the description adds rich behavioral context: data source (US Census port-level records), time range (2017→present), revision tracking, HS6 detail from 2024, the exclusion of duty from customs value, and the automatic computation of duty and landed_vs when origin and 6-digit commodity are provided. This goes far 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 long but every sentence earns its place. It front-loads the core purpose, then systematically covers filters, data quality, computed outputs, usage examples, and a warning. There is no redundant 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?
Given the tool's complexity and the presence of an output schema, the description is fully complete. It covers data provenance, time coverage, parameter nuances, special computed outputs, usage examples, and the absence of an API key. No gaps remain for the agent to infer.
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?
Although schema coverage is 100%, the description adds crucial context to each parameter: origin accepts country names or Schedule C codes, commodity can be HS2 chapter names or HS codes, gateway examples are given, and months default/max are clarified. It also explains how parameters interact (origin+6-digit commodity triggers duty and landed_vs). This meaningfully enriches 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 opens with a specific verb ('Query') and clearly identifies the resource: US containerised import trade with monthly weight and customs value via 8 gateways. It explicitly differentiates itself from the sibling tool 'compare' by stating 'no need to call compare', making its unique scope 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?
Provides explicit when-to-use guidance with concrete examples ('Ask it things like: US furniture imports from Vietnam monthly...'), an exclusion ('no need to call compare'), and a critical caution ('never compare invoice $/kg across origins without it'). This clearly signals when the tool should be selected over alternatives.
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.
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 import tariff lookup against the official USITC Harmonized Tariff Schedule
Source-linked US tariff and trade-action changes: legal status, effective dates, dated archive.
HTS MCP — US import tariff rates via the USITC Harmonized Tariff Schedule.
Add one secure layer between your agents and this server.