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?

Goes far beyond the annotations (readOnly/destructive) by detailing exact outputs: aligned series, changes, ratio, stated finding, and the special landed_cost/FOB headroom calculation for origin comparisons. It also discloses limitations and exceptions, such as nationwide receipts for duty measures.

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 (three paragraphs) but well-structured and front-loaded with the core function. Most sentences add value, though the extended landed_cost explanation is detailed and arguably could be tightened without losing essential information.

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 tool with no output schema, the description covers the main outputs and use cases comprehensively, including a special case for origins. It misses details on the 'detail' parameter levels (answer/standard/full) and month range, which are important for agent invocation but not fatal given the schema provides defaults and enums.

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?

Adds meaning to key parameters beyond the schema: clarifies what subject_a/b represent (countries, chapters, gateways), explains the measure enum values (weight, value, unit value, tariff burden, duty paid), and specifies the commodity/origin relationship. However, it does not explain the 'detail' or 'months' parameters, which are undocumented 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 states the tool compares two subjects side-by-side over the same months, with specific verbs ('put', 'compute the difference') and resources (origin countries, commodity chapters, gateways). It distinguishes from siblings by focusing on direct comparison and provides concrete examples of intended queries.

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 usage examples ('Use for "is trade shifting from China to Vietnam"...') and constraints: both subjects must be same kind, call twice for more than two, and burden/duty measures unavailable for gateway. This gives clear when-to-use and when-not-to-use guidance without naming alternatives directly.

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 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.

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 this as read-only and non-destructive, and the description adds beyond them: the grade rule (OBSERVED / REPORTED / MODELLED; modelled quantities are never quotable as measurements), the offer-counted-tonnes alternative, and contextual detail about the suspended India series. No API key requirement is also disclosed.

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, front-loading the router purpose and sub-tool list. Every sentence earn its place: invocation, sub-tool descriptions, grade rule, usage disambiguation, and auth note.

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 with no output schema and a nested arguments object, the description covers invocation, sub-tool selection, key domain constraints, alternatives, and auth. It is slightly less explicit about per-sub-tool argument schemas or return shapes, but the given context is strong enough for an agent to select and begin invoking it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% for the router's two parameters with an enum for tool. The description adds meaning by showing the call shape '{tool, arguments}' and giving a concrete example argument object for describe_series. It slightly stops short of fully documenting the argument requirements of every sub-tool, but it conveys enough for a router.

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 registry tools, enumerates all four sub-tools, and gives a one-line purpose for each. This distinguishes it from the trade/tariff siblings and leaves no ambiguity about the resource it operates on.

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

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

It explicitly says 'Most questions never need this router: trade/tariff answers live in the primary tools,' giving when-not-to-use guidance and pointing to alternatives. It also states the invocation pattern and that no API key is required.

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 mark readOnlyHint=true and destructiveHint=false, revealing it as a safe read operation. The description adds valuable context: suspended periods are deliberately withheld and counted, fully-suspended spans fail with a reason, and it discloses free/CC BY 4.0 licensing and no API key requirement. This goes beyond annotations, though it does not cover pagination or rate limits, which are not critical 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?

Three sentences, each purposeful: the first states the action and data scope, the second clarifies edge-case behavior, and the third covers licensing and authentication. Front-loaded with the core functionality, no redundancy or fluff. Efficient and well-structured.

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 tool has an output schema, so return format is presumably covered elsewhere. The description covers the data types, special handling of suspended periods, licensing, and auth. The only notable gap is the 'series' parameter—what a valid series identifier looks like—but this is a minor omission for a data-fetch tool with moderate complexity. Overall, the agent has enough to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 75% (three of four parameters have descriptions: 'Inclusive end', 'Inclusive start, YYYY-MM-DD or YYYY-MM', 'Max rows, default 2000'). The description adds no additional meaning to parameters; it only states the general purpose. Since schema coverage is high, baseline 3 is appropriate, but the 'series' parameter remains undescribed both in schema and description, so no value is added 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 states a specific verb ('Fetch') and a precise resource: 'data of a series' with enumerated content types (monthly US port trade, tariff rates, collected duty) and format ('as periods and values'). This strongly distinguishes it from siblings like tariff_lookup or trade_query by clarifying it returns time-series data. No ambiguity about what the tool does.

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 on when to use this tool versus alternatives. It does not mention conditions like 'use for time-series queries' or name any sibling tools. The description implies a series-based use case but offers no explicit routing or exclusions. Agents have to infer when to select this over trade_query or tariff_story.

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?

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.

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.

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

Annotations already mark readOnly=true and destructive=false, but the description adds critical behavior: data comes from official duty receipts, resolves HS codes and reports confidence, includes a warning that 2025-26 rates changed, and notes no API key required. This goes well 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 longer than average but front-loaded with the imperative 'USE THIS FIRST' and each sentence adds substantive guidance. The phrase 'Trimtab HAS this data' is slightly promotional but reinforces reliability. No wasted 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?

For a tool with no output schema, this description is remarkably complete: it covers purpose, data sources, output components, exclusions, alternatives, prerequisites (none), and operating conditions. An AI agent would know exactly when and how to invoke this 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 coverage is 100%, so baseline is 3. The description adds value by explaining the hs/product 'OR' relationship and the confidence reporting on resolution, which is not in the schema. However, most parameter semantics are already in the schema descriptions.

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 'USE THIS FIRST' and explicitly states it answers 'what is the tariff on X from Y' or comparison questions, listing the exact outputs (actual paid rates, MFN base, trade-war measures, change, rulings). It distinguishes from siblings by declaring 'It replaces hs_search + tariff_lookup + tariff_burden.'

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 ('for ANY...') and when-not-to-use ('Do NOT use for trade volumes (trade_query) or as customs advice'). Names the alternative tool for trade volumes and orders usage with 'USE THIS FIRST'.

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 read-only and non-destructive annotations, the description adds substantive behavioral context: data is 'mirrored and revision-tracked' (implying results may be revised), coverage starts '2017→present (HS6 detail from 2024)', and it warns 'The customs value here excludes duty, so never compare invoice $/kg across origins without it.' It also notes 'No API key required.' No contradiction 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 a single dense paragraph but front-loaded with the core purpose. Each sentence adds substantive information, though it could be broken into clearer segments. It is appropriately sized for the complexity of the tool, with no 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?

Given the complex conditional behavior, rich schema, and output schema, the description fully covers data coverage, return values, caveats, examples, and authentication. It doesn't need to explain share_draft because the schema already covers it, and output schema handles return details.

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 conditional semantics: 'When you give an origin and a 6-digit commodity it ALSO returns duty and landed_vs' and specifies example values ('China, Vietnam, India — 30 largest origins', 'us_la_longbeach, savannah'), going beyond the schema's basic parameter descriptions.

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 resource: 'Query US containerised import trade directly: monthly weight (kg) and customs value (USD) through the 8 major US container gateways, filterable by origin country... commodity... and gateway.' It clearly distinguishes from the compare sibling by stating 'no need to call compare' for landed-cost comparisons.

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 not to use an alternative: 'That is the buyer-pitch number, answered in this one call — no need to call compare.' It also provides concrete example queries ('Ask it things like: US furniture imports from Vietnam monthly; plastics through Houston; imports from India last 36 months') illustrating when to invoke the tool.

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