us-tariff-ledger

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.

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral detail: the output includes aligned series, changes, ratio, and a finding, and it notes that burden/duty data come from nationwide receipts. It could further disclose return formatting, but the added context goes beyond 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 moderately long but every sentence carries information, from purpose to usage examples to constraints. It is well-structured with a clear opening, examples, and restrictions, though it could be tightened slightly without losing value.

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 8 parameters, no output schema, and minimal annotations, the description covers the essential contexts: purpose, usage, return structure, measurement constraints, and authentication (no API key). It does not explicitly mention default months or exact input formats, but those are partially inferred from the schema or are not critical for invocation.

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 only 25% (only origin and commodity have descriptions), so the description must compensate. It explains the kind values, the measure enum options, and the requirement that both subjects be the same kind. It leaves detail and months partially unexplained, but the core parameters (subject_a, subject_b, kind, measure) are given semantic meaning.

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 action ('Put two subjects on the same axis... compute the difference') and clearly enumerates supported subject kinds and measures. It distinguishes this tool from siblings by focusing on pairwise comparison, explicitly saying 'to compare more than two, call twice.'

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 concrete example uses ('is trade shifting from China to Vietnam', etc.) and explicit exclusions: subjects must be the same kind, the tool is limited to two subjects per call, and burden_pct/duty_usd are unavailable for gateway. This is clear when-to-use and when-not-to-use guidance.

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

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

Annotations already mark it as read-only and non-destructive. The description adds useful behavioral context: it states the data sources (7 years of NOAA AIS and US Census port records), the return structure (registration, verdict, evidence, falsification test), and that 'No API key required.' This goes 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 a single paragraph that front-loads the core purpose, then provides a list of examples and data sources. Every sentence contributes meaningful content, though it is longer than the minimal required due to the enumeration of shocks.

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 tool with one optional parameter and no output schema, the description adequately explains what the tool returns and the data it draws on. It does not delve into individual study mechanics but is sufficient for an agent to select and 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?

The input schema fully describes the only parameter (slug) with examples and behavior when omitted (list all studies). The description does not add any parameter-level detail, so it adds no semantic value beyond the schema. Baseline 3 applies due to 100% schema coverage.

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 it provides 'pre-registered event studies of every major shock to US containerized trade 2018–2026' and lists specific examples (tariff waves, COVID, LA/LB queue crisis, etc.). This distinguishes it from sibling tools by focusing on event studies rather than trade queries or tariff lookups.

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 strong context for when the tool is relevant (major shocks to US trade) but does not explicitly state when to use it instead of sibling tools or mention exclusions. It implies usage for understanding trade disruptions but lacks direct comparative guidance.

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

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.

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

Annotations already mark readOnlyHint=true and destructiveHint=false, but the description adds substantial behavioral context: the frozen AIS archive is time-bound, modelled quantities are 'never quotable as measurements,' and no API key is required. These are meaningful constraints beyond the annotations, with no contradiction.

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?

Although longer than typical, every sentence earns its place: the router intro, categorized sub-tool lists, grade rule, and exclusion note are all essential. The structure with REGISTRY / FROZEN AIS ARCHIVE / GRADE RULE is front-loaded and easy to scan, making the length justified.

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 router exposing 8 sub-tools with no output schema, the description thoroughly covers tool purpose, temporal limitations, data quality rules, and usage boundaries. It tells the agent everything needed to decide whether to use this tool and which sub-tool to invoke, making it contextually 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 covers both parameters (tool enum, arguments object) with an example. The description adds meaning by explaining each sub-tool's purpose (e.g., 'describe_series (grade, coverage, citation string)') and providing a concrete arguments example. It doesn't exhaustively document each sub-tool's arguments, but the high schema coverage and explanatory context are sufficient.

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 clear statement: 'Router to the ledger's meta and archive tools — call with {tool, arguments}.' It then enumerates the 8 sub-tools with concise functional labels, and explicitly distinguishes itself from siblings with 'Most questions never need this router: trade/tariff answers live in the primary tools.' This provides a specific verb, resource, and clear differentiation.

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?

Usage guidance is explicit: it separates REGISTRY from FROZEN AIS ARCHIVE, states the archive's date range and that it 'cannot answer anything current,' and gives a clear exclusion: 'Most questions never need this router.' This tells the agent exactly when to use it versus the primary trade/tariff tools.

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

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.

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.

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

Annotations already indicate read-only and non-destructive behavior. The description adds meaningful behavioral detail: suspended periods are withheld and counted (not silently dropped), and fully-suspended spans fail with a reason. It also notes licensing and no-auth requirements, going beyond the structured 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?

Two tightly written sentences front-load the action and examples while covering licensing and important edge-case behavior. No filler or redundant restating of the tool name exists.

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 available and four simple parameters, the description covers core behavior, edge cases, and access requirements well. It lacks sibling differentiation and exact series-ID syntax, but for a straightforward fetch tool it 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 covers 75% of parameters with clear from/to/limit descriptions. The description contributes little additional parameter meaning except giving examples of valid series content (e.g., 'vessel events', 'ETA reliability'), which helps somewhat but doesn't fully define the series identifier format.

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 action ('Fetch the data of a series') and specifies the resource with concrete examples ('monthly US port trade by country and commodity, vessel events, ETA reliability'). This distinguishes it from siblings like trade_query or commodity_profile by emphasizing it returns periods and values for named series.

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?

No guidance is provided on when to use this tool compared to alternatives like trade_query or compare. The description only mentions free availability and no API key, which is access context, not usage direction.

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

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.

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

Annotations already establish this as a read-only, non-destructive operation. The description adds behavioral context by stating that it returns both effective rate and overall burden 'with caveats,' and that data is cross-checked against Treasury receipts. This adds credibility but does not disclose specifics of the caveats or any limitations (e.g., data lag, excluded origins). Given the annotations cover the safety profile, a 4 is appropriate.

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 concise, front-loaded with the core value proposition, and follows a logical structure: what, how, scope, output, examples, validation, and access. Every sentence adds meaning without redundancy. It is only slightly long but remains efficient and scannable.

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 a rich output schema present, the description does not need to explain return values. It covers the data source, time range, geographic scope, aggregation keys, metric types, and caveats. It also provides concrete examples and an assurance of cross-checking, making it complete for an AI agent to select and invoke the tool appropriately.

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 of parameter descriptions, including the 30-largest-origins constraint and the commodity options. The description adds some semantic value by explaining that commodity can be an HS2 chapter name or 2/6-digit code and by grounding usage in examples, but it does not significantly elaborate beyond the schema. This meets the baseline without exceeding it.

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 purpose: reporting actual tariff payments from official receipts, not rulebook rates. It specifies the metrics (monthly duty collected, dutiable value, consumption value), granularity (by origin and commodity), time range (2017→present), and level (US national). This differentiates it from siblings like tariff_lookup, and the examples (China effective rate, furniture from Vietnam, toys from China) make 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 gives clear context for when to use it: when you need actual receipts-based tariff data rather than statutory rates. The phrase 'not the rulebook' implicitly contrasts with tariff_lookup, and the examples illustrate typical use cases. However, it does not explicitly name alternative tools or state when not to use it, so it falls short of full explicit guidance.

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

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

Beyond the readOnlyHint/destructiveHint annotations, the description discloses a critical behavioral nuance: measures are matched by ORIGIN and SECTOR, not necessarily by code, and product-specific provisions may not apply. It also warns against summing values and states that receipts_reality is the authoritative figure, adding significant interpretive 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?

Approximately 100 words, yet every sentence adds value: purpose, critical warnings, disclaimer, example, and no-auth note. The structure front-loads the action and uses clear formatting for the important caveat.

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 thoroughly explains what the tool returns and how to interpret it, including potential traps and the composed truth. It also covers access requirements (no API key) and provides a vivid example, making it fully self-contained for an agent.

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, defining hs and origin with their roles. The description repeats the origin effect ('adds in-force measures and receipts reality') and provides an example, but adds no new parameter syntax or meaning 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 opens with a specific verb and object: 'Raw tariff-schedule lookup for one HS code', then enumerates the exact data returned (MFN base rate, Chapter-99 provisions, border receipts). This clearly differentiates it from siblings like hs_search or tariff_story and gives a concrete example.

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 strong guidance on how to interpret results (never add addon_pct values, quote receipts_reality) and notes the tool is 'raw' and 'not customs advice'. However, it does not name alternative sibling tools or explicitly state when to use a different tool instead.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds rich behavioral context beyond annotations: it accepts either an HS code or a plain-language product, resolves the code and reports confidence, states that omitting origin gives 'much weaker' results, and notes 'No API key required.' It does not disclose potential failures or edge cases, but the added context is substantial.

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 dense paragraph that is front-loaded with the main purpose. Every sentence contributes meaningful detail (outputs, input modes, usage guidance, exclusions). It is somewhat long but appropriate for a tool with five parameters and no output schema. A bulleted list could improve scannability, but the structure is effective.

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 tool with no output schema, the description covers the core behaviors, parameter interactions, use cases, and exclusions. It names the data sources and output components, and it explains the effect of the detail parameter. It does not mention error handling or response format, but the overall completeness is high for the 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 baseline is 3. The description adds meaning beyond the schema: it clarifies the OR relationship between hs and product, explains the detail parameter levels with approximate token counts, and warns that omitting origin weakens results ('overlays are origin-specific'). This goes beyond simple parameter listing.

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 purpose: 'The complete tariff answer for one product from one origin, in a single call.' It enumerates specific outputs (actual paid duties, MFN base rate, trade-war measures, citations, change shape, rulings count) and distinguishes itself from siblings ('replaces hs_search + tariff_lookup + tariff_burden sequence').

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?

Explicit guidance is provided: 'USE THIS FIRST for any "what is the tariff on X from Y" question' and 'Do NOT use it for trade volumes (trade_query), a country overview (origin_profile), or as customs advice.' This tells the agent exactly when to pick this tool and when to choose alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable context beyond these: data source ('US Census port-level records'), revision tracking, time range ('2017→present', HS6 detail from 2024), and 'No API key required.' This enriches the agent's understanding without contradicting 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 a bit longer than the shortest possible but every sentence adds value: the first sentence gives core functionality, the second provides data provenance and time range, the third gives example queries, and the last states authentication requirements. It is well-structured and not redundant, though it could be tightened slightly.

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 moderate complexity, the description covers all essential aspects: what data is returned (weight and value), available filters, time range, data source, example use cases, and authentication. An output schema exists, so return values don't need to be spelled out. This is highly complete 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 100% and each parameter has a description. The description adds extra meaning by giving concrete examples of valid values (e.g., 'China, Vietnam, India — 30 largest origins', 'furniture/plastics/electronics', 'us_la_longbeach'), which helps clarify the expected input format and domain, going beyond the bare 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 states a specific verb ('Query') and resource ('US containerised import trade') with clear scope: monthly weight and customs value through 8 gateways, filterable by origin, commodity, and gateway. It distinguishes from siblings like origin_profile or commodity_profile by emphasizing direct multi-filter queries, making its unique role clear.

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 and several concrete example queries ('US furniture imports from Vietnam monthly; plastics through Houston; imports from India last 36 months'), which implicitly indicate when to use this tool. However, it does not explicitly name alternative sibling tools or state when not to use it, so it lacks explicit exclusions.

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